@torrent-tv/proxy 2.50.0 → 2.52.0

package/CHANGELOG.md

@@ -1,3 +1,23 @@
+## 2.52.0
+
+- **Fix**: A file opened at a position puts the SOUND there too. Where the audio rendition starts is computed from where the viewer is, and that reading consulted only two things — a position seeked to, and the last segment the session had served — both written by events that have not happened yet at the moment a file is opened partway through. The answer was therefore zero. Field 2026-08-21, `Minions.and.Monsters.1080p.mkv` reopened from the address bar at 52:07: the picture session was created at `start=3130s` and ran from segment #781, and half a second later the audio rendition was created at `start=0s` with no `-ss` at all and set about re-encoding the film from the beginning. The player asked both for #782; the picture had it, the sound reached 57.5 s of 3130 in the 45 s the request lasted and then answered 404 — which the viewer was shown as "the proxy accepted the request but sent no video". The position a session was OPENED at is now the third reading, and `resolveViewerPosition` is pure and tested. The same calculation prepares a track for a language change, so that case is covered by the same fix.
+- **Fix**: The line describing a swarm answers the question it is asked. It printed `peers=N` beside `wires=?`, which reads as two quantities of which one is unknown — while WebTorrent's `numPeers` IS `wires.length` (`lib/torrent.js`, identically in 2.8.5 and 3.0.21), so the first was the connection count and the second was a field that has never printed anything in any line it has ever written: the torrent lives on a worker thread and that property does not exist on the side doing the printing. What was missing was the other half of the question, and it is now there — how many peer addresses the client HOLDS, how many are queued to be tried, and what the tracker said the swarm has. Five offered and none connected is a connectivity fault; nobody offered is a supply fault; they need opposite investigations and one line now tells them apart. What the trackers said is kept PER TRACKER and reported as the best answer any of them gave: they answer separately, and a dead one replying `0` after a live one replied `500` would otherwise turn "several offered" into "nobody offered", inverting the very distinction being drawn.
+- **New**: The wait for the first connected peer is measured, said once when it ends, and carried in the stats while it is still going. Measured 2026-08-21 on `JUFD665.mp4`: the tracker answered `seeders=5` at 13:40:30 and the first wire arrived at 13:44:47 — 4 min 17 s of a viewer watching an unexplained wait, after which the file's 12 MiB of edges arrived at 6.8 MB/s and the plan finished in three seconds. The whole cold start was that one number, and it was neither counted nor shown. The watching is attached to what `add` returns rather than inside its ready callback, because for a magnet everything it watches happens before `ready`: peer discovery starts before the metadata arrives, so the trackers' answers land before any listener exists, and the peer that DELIVERED the metadata connected before `ready` fired — `wire` is emitted on connection and never replayed. It is also attached once per torrent: WebTorrent answers a duplicate add by handing back the torrent it already has, and re-attaching reset the timing of a live swarm, after which the next connection would print "first peer connected after 0.3s" about a torrent that had been connected for minutes.
+- **Fix**: One name for a torrent, and it is the infohash. The pool's `added`, `announce` and `warning` lines were labelled with the first eight characters of a sha1 of the SOURCE BYTES, the upload lines used the infohash, and the stats line used the registry's own key — three different hashes of one film, printed in the same second, none matching. The infohash is now on all of them, and on every stats line rather than only on the ones that look empty.
+- **Chore**: `askedFor=0` is called `fileIndex=0`. It is the index of the file being asked about, and it was printed under a name that reads as "nothing was asked for" — in a line whose subject is a download that is not happening.
+
+## 2.51.0
+
+- **Fix**: A run is POSITIONED where the player was told the segment begins, on the same table its cuts are stated on. There are two boundary tables — the one the playlist text was written from, which never changes, and the live one, corrected as produced segments reveal where the file's cuts truly are. 2.45.0 moved the CUT LIST onto the published table and left the position on the live one, and that is one fault rather than two: `-segment_times` are measured from wherever the run really began, so any distance between the two carries into EVERY cut the run makes. The corrections run backwards, so each restart began a little earlier than the grid its cuts were stated on, and because the corrections accumulate, so did the distance. Measured 2026-08-21 on `JUFD665.mp4` — an MP4 whose index was read cleanly, 1765 keyframes, served by copy: after one seek restart a produced segment held the boundary **two** places before its own number (16.684 s, exactly 2.0000 segments), after the next restart **four** (33.5 s). The player's buffer then stops extending at all, because every fragment's content lands before the time its playlist entry names: `bufferEnd` stood still at 4571.1 s through four `frag-far` warnings until hls.js gave up and jumped the viewer 16.8 s forward. Four of those jumps in one window is what the viewer reported as sticking on every seek.
+- **Fix**: The line about a segment that began away from its grid follows the numbers instead of the branch it is printed from. On the copy path it always read "the container's keyframe index disagrees with the file", including in the case this code's own neighbouring comment defines as a fault in this code — a segment holding another boundary **of the same list**. It now says which of the two it is, because they need opposite fixes and that sentence is what sent the reading of the session above after the file instead of after the arithmetic. The soundtrack's variant of the sentence stops claiming anything about a keyframe index: a soundtrack has no keyframes and is cut exactly where it was asked to be.
+- **New**: A run says where it was positioned — the time, the boundary it came from, that boundary's time in the PUBLISHED table and in the LIVE one, the distance between them, and the number it starts counting from. Four numbers whose disagreement was invisible everywhere else.
+- **New**: A correction to the live boundary table states the total drift it is part of. Corrections are applied one boundary at a time and each is small enough to look harmless; nobody was watching the sum, which is the quantity that actually moves the cuts.
+- **Fix**: The realignment that starts the sound where a copied picture truly begins is given that instant EXPLICITLY. It used to be smuggled through the live boundary table — the correction wrote the measured time there and the restarted run read its position from the same place — which stops working the moment a run positions itself on the table the player holds, as it now must. Smuggled, the restart would land exactly where it already was: picture and sound stay apart AND a healthy soundtrack run is discarded for nothing, which is the shape the field already showed on 2026-08-21 — eleven audio restarts in under four minutes, eight of them dying with `run had produced 0.0s`.
+- **Fix**: What a run was asked for is taken from the run rather than looked up again in a table. Two lines did the second — the one reporting where a run landed, and the one explaining a held segment — and once the position moved to the published grid they could disagree with the run by the distance between the two tables: a perfect landing reported as a drift, a real drift of the same size cancelled to zero, and a held segment printing a negative "produced" that sends the reader after the torrent when the encoder is the subject.
+- **New**: The player's own "this fragment is nowhere near my buffer" reading is answered instead of being left in its console. `POST /api/transcode-sessions/:id/fragment-far` takes the report and the proxy replies in the log with the one fact only this side holds: which boundary the segment of that number really begins at, and whether that is the one its number claims. The report says which stream it is about, and a report about the soundtrack is answered from the soundtrack's own session: picture and sound are produced by two sessions positioned by two runs, which is how they come apart, so answering one from the other's records would state something confident about the wrong stream. Diagnostic only — nothing is repositioned on the strength of a browser's reading, because a wrong answer there would restart an encoder a viewer is waiting on.
+- **Fix**: The DHT is given entry points that answer. Measured 2026-08-21 from the addon host: of the three bootstrap nodes the library ships, `router.bittorrent.com` and `router.utorrent.com` replied to nothing while a control datagram to a DNS server came back in 20 ms, and the third, `dht.transmissionbt.com`, is alive — it answered `find_node` with eight nodes — but on a host with global IPv6 its name resolves to an IPv6 address first while the DHT's socket is IPv4, so by name it was never reached. The list now carries a live node, and the names are resolved to IPv4 here rather than left to whichever family the host prefers. Measured on that host: 0 nodes after 21 s by name, 22 nodes in 5 s by address. The resolution is capped at two seconds per name, because it is awaited before the torrent client exists and a host whose resolver black-holes would otherwise hold that thread for c-ares' own four tries with nothing said. What it cost: on `JUFD665.mp4` the tracker answered `seeders=5` at 13:40:30 and the first peer connected at 13:44:47 — 4 min 17 s of a viewer watching an unexplained wait with an empty routing table beside them. A private torrent still ignores the DHT, by specification.
+- **New**: The size of the DHT's routing table is said a minute after start, and an empty one is said as a warning. A bootstrap list rots — that is exactly what had happened here — and nothing reported it for as long as it was wrong, so the next list to die would be found the same way this one was: by hand, after a viewer waited four minutes.
+
 ## 2.50.0
 
 - **Fix**: An AVI seek is asked for late enough to survive the container's own arithmetic. AVI names a keyframe by its frame NUMBER, and `services/container-index/avi.js` turned that into a time by multiplying by the frame duration the header declares — which lands 10-44 ms from the presentation time the demuxer computes, always under one frame (measured 2026-08-21 against the files themselves: 1196 index entries against 1196 real keyframes and 901 against 901, the frames exactly right and only their names off). A name sitting just BELOW its real keyframe seeks to before it and lands on the one before that, which is the same fault the landing offset already exists for. The reader now declares how far its times may be, and the request carries that on top. Matroska and MP4 declare nothing, because they state instants outright — nine files and 11 665 keyframes with not one disagreement.

package/package.json

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

package/routes/api/sources/stats/get.js

@@ -61,6 +61,37 @@ export async function handleApiSourceStatsGet(req, reply, { sourceRegistry, torr
     stats.headerBytes != null
       ? `${stats.headerDownloadedBytes}/${stats.headerBytes}B`
       : "n/a";
+  // The swarm, said so that the question this line is asked can be answered
+  // from it. "Connected" and "known" are different numbers and their
+  // difference is the diagnosis: a tracker offering five while we are
+  // connected to none is a connectivity fault, and nobody offering anything is
+  // a supply fault. Until 2026-08-21 the line printed `peers=` beside
+  // `wires=?` — two quantities of which one looked unknown, while in truth the
+  // first WAS the connection count and the second was a field that never
+  // printed anything, because the torrent lives on another thread and the
+  // property does not exist on this side of it.
+  const known = stats.knownPeers === null || stats.knownPeers === undefined ? "?" : stats.knownPeers;
+  const queued = stats.queuedPeers === null || stats.queuedPeers === undefined ? "?" : stats.queuedPeers;
+  // The BEST answer any tracker gave, and how many answered — not the most
+  // recent one. Trackers answer separately, and a dead one replying `0` after a
+  // live one replied `500` would otherwise turn "several offered" into "nobody
+  // offered", which is the distinction this whole line exists to make.
+  const offered = stats.trackerSeeders === null || stats.trackerSeeders === undefined
+    ? (stats.trackersAnswered
+        // Answered, and none of them knew of anybody — a different state from
+        // "no tracker has replied at all", and the line must not read as the
+        // second when it means the first.
+        ? `${stats.trackersAnswered} tracker(s) answered, none reported a count`
+        : "no tracker answer yet")
+    : `${stats.trackersAnswered ?? "?"} tracker(s) offered up to ${stats.trackerSeeders} seeders ` +
+      `${stats.trackerLeechers ?? "?"} leechers`;
+  // The wait for a first peer can be the whole of a cold start — 257 s of it,
+  // measured — and it was neither counted nor shown.
+  const firstPeer = Number.isFinite(stats.secondsToFirstPeer)
+    ? ` firstPeerAfter=${stats.secondsToFirstPeer.toFixed(1)}s`
+    : Number.isFinite(stats.secondsWaitingForFirstPeer)
+      ? ` noPeerFor=${stats.secondsWaitingForFirstPeer.toFixed(1)}s`
+      : "";
   // When the answer is empty, say WHICH thing is missing. Field 2026-08-05: a
   // source reported `peers=0 file=n/a header=n/a` for minutes while that very
   // torrent was announcing to trackers with hundreds of seeders — and the line
@@ -70,12 +101,17 @@ export async function handleApiSourceStatsGet(req, reply, { sourceRegistry, torr
   // answerable from the log rather than by reasoning about it afterwards.
   const emptyAnswer = stats.fileProgress == null || (stats.numPeers === 0 && torrent.done !== true);
   const detail = emptyAnswer
-    ? ` | infoHash=${String(torrent.infoHash).slice(0, 8)} files=${torrent.files?.length ?? "?"}` +
-      ` askedFor=${fileIndex ?? "none"} resolved=${torrent.files?.[fileIndex ?? -1] ? "yes" : "no"}` +
-      ` wires=${torrent.wires?.length ?? "?"} done=${torrent.done === true}`
+    ? ` | files=${torrent.files?.length ?? "?"}` +
+      ` fileIndex=${fileIndex ?? "none"} resolved=${torrent.files?.[fileIndex ?? -1] ? "yes" : "no"}` +
+      ` done=${torrent.done === true}`
     : "";
+  // The infohash is on EVERY line, not only on the ones that look empty: it is
+  // the one identifier the pool's own lines, the worker's and this one share,
+  // and a line that carries it can be lined up with them without a guess.
   logger.info(
-    `[stats] ${sourceKey.slice(0, 8)} peers=${stats.numPeers} down=${downKbps}KB/s file=${filePct} header=${header}${detail}`
+    `[stats] ${sourceKey.slice(0, 8)} ${String(torrent.infoHash).slice(0, 8)} ` +
+    `peers=${stats.connectedPeers ?? stats.numPeers} connected of ${known} known (${queued} queued, ${offered})` +
+    `${firstPeer} down=${downKbps}KB/s file=${filePct} header=${header}${detail}`
   );
 
   return reply.send(stats);

package/routes/api/transcode-sessions/fragment-far/post.js

@@ -0,0 +1,60 @@
+/**
+ * Accept the player's report that a delivered fragment sits far from the edge
+ * of what it has buffered.
+ *
+ * This is the earliest statement that exists of a stream coming apart, and
+ * until now it lived only in the browser's console. Measured 2026-08-21 on
+ * `JUFD665.mp4`: four of these across half a minute, each naming a gap of
+ * ~33.5 s, while the buffer stood still at 4571.1 s — and then hls.js gave up
+ * and jumped the viewer 16.8 s forward. The proxy is the only side that can say
+ * what the gap MEANS, because only it knows which boundary the segment it
+ * produced actually holds, and whether that is the one its number claims.
+ *
+ * POST /api/transcode-sessions/:sessionId/fragment-far
+ * Body: { sn: number, track?: string, fragStartSec: number, bufferEndSec: number, currentTimeSec: number }
+ *
+ * `track` is hls.js's own name for the stream the fragment belongs to ("main"
+ * or "audio"). It matters because picture and sound are produced by two
+ * different sessions positioned by two different runs — which is how they come
+ * apart in the first place — so a report answered against the wrong one is a
+ * confident statement about a stream nobody asked about.
+ *
+ * Diagnostic only — it changes nothing about the encode. Invalid body → 400,
+ * unknown session → 404, ok → 204.
+ *
+ * @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 handleApiTranscodeSessionFragmentFarPost(req, reply, { hlsSessionManager }) {
+  const sessionId = typeof req.params.sessionId === "string" ? req.params.sessionId : "";
+  const body = req.body && typeof req.body === "object" && !Array.isArray(req.body) ? req.body : {};
+  const sn = Number(body.sn);
+  const track = typeof body.track === "string" ? body.track : "";
+  const fragStartSec = Number(body.fragStartSec);
+  const bufferEndSec = Number(body.bufferEndSec);
+  const currentTimeSec = Number(body.currentTimeSec);
+  if (
+    !sessionId ||
+    !Number.isInteger(sn) ||
+    sn < 0 ||
+    !Number.isFinite(fragStartSec) ||
+    !Number.isFinite(bufferEndSec) ||
+    !Number.isFinite(currentTimeSec)
+  ) {
+    return reply.code(400).send({ error: "sn (integer >=0), fragStartSec, bufferEndSec and currentTimeSec are required." });
+  }
+
+  const recorded = hlsSessionManager.recordFragmentFar(sessionId, {
+    sn,
+    track,
+    fragStartSec,
+    bufferEndSec,
+    currentTimeSec
+  });
+  if (!recorded) {
+    return reply.code(404).send({ error: "Transcode session was not found." });
+  }
+  return reply.code(204).send();
+}

package/server.js

@@ -26,6 +26,7 @@ import { handleApiTranscodeSessionsPost } from "./routes/api/transcode-sessions/
 import { handleApiTranscodeSessionsProgressGet } from "./routes/api/transcode-sessions/progress/get.js";
 import { handleApiTranscodeSessionReleasePost } from "./routes/api/transcode-sessions/release/post.js";
 import { handleApiTranscodeSessionNetReportPost } from "./routes/api/transcode-sessions/net-report/post.js";
+import { handleApiTranscodeSessionFragmentFarPost } from "./routes/api/transcode-sessions/fragment-far/post.js";
 import { handleApiTranscodeSessionSeekPost } from "./routes/api/transcode-sessions/seek/post.js";
 import { handleStreamGet } from "./routes/stream/get.js";
 import { handleTranscodeSessionFileGet } from "./routes/transcode/session-file/get.js";
@@ -244,6 +245,9 @@ export async function startProxyServer({ host, port, transcodeAudio, ffmpegBin,
   app.post("/api/transcode-sessions/:sessionId/net-report", async (req, reply) =>
     handleApiTranscodeSessionNetReportPost(req, reply, { hlsSessionManager })
   );
+  app.post("/api/transcode-sessions/:sessionId/fragment-far", async (req, reply) =>
+    handleApiTranscodeSessionFragmentFarPost(req, reply, { hlsSessionManager })
+  );
   app.post("/api/transcode-sessions/:sessionId/seek", async (req, reply) =>
     handleApiTranscodeSessionSeekPost(req, reply, { hlsSessionManager })
   );

package/services/hls-session-manager.js

@@ -422,6 +422,12 @@ const LOOKAHEAD_RESUME_SECONDS = 60;
 // encoding 125 s of content before reaching the viewer's position. Field
 // 2026-08-02: a seek took 56 s, of which ~50 s was this backoff.
 const SEEK_BACKOFF_SEGMENTS = 1;
+
+// How many produced segments' true start times to remember, so a player's
+// report about one of them can be answered. Two hundred is about twenty
+// minutes of playback at these segment lengths — far more than the recent past
+// a stall report can be about, and small enough to be free.
+const TRUE_START_MEMORY = 200;
 // How long to wait for a scrub to stop moving before acting on it. Small,
 // because the browser already collapses a drag into ONE report
 // (`SEEK_REPORT_DEBOUNCE_MS`, 300 ms) and only reports where it settled — this
@@ -1176,6 +1182,97 @@ export function segmentCutTimesFrom(boundaries, startIndex) {
   return times;
 }
 
+/**
+ * Where the viewer is, from the three things that can say so.
+ *
+ * In order, because each is a better answer than the next and each may be
+ * absent:
+ *
+ * 1. a position they seeked to — they said it themselves;
+ * 2. the start of the last segment this session actually served — where the
+ *    reading is;
+ * 3. **the position the file was OPENED at.**
+ *
+ * The third used to be missing, and its absence made the answer zero at exactly
+ * the moment it is asked. Both of the others are written by things that have
+ * not happened yet when a file is opened at a position — the first by a seek,
+ * the second by a segment served — so a session created to begin at 3130 s
+ * answered "the viewer is at the beginning". That is not a cautious default; it
+ * is a wrong answer, and the soundtrack acts on it.
+ *
+ * Field 2026-08-21, `Minions.and.Monsters.1080p.mkv` reopened from the address
+ * bar at 52:07: the picture session was created at `start=3130s` and ran from
+ * segment #781; half a second later the audio rendition was created from this
+ * reading — `start=0s`, no `-ss` at all — and set about re-encoding the film
+ * from the beginning. The player asked both for #782. The picture had it. The
+ * sound reached 57.5 s of 3130 in the 45 s the request lasted, then answered
+ * 404, which the viewer was shown as "the proxy accepted the request but sent
+ * no video".
+ *
+ * @param {{ seeked?: number, lastRequestedStart?: number | null, openedAt?: number }} readings
+ * @returns {number} Seconds, never negative.
+ */
+export function resolveViewerPosition({ seeked, lastRequestedStart, openedAt }) {
+  if (Number.isFinite(seeked) && seeked > 0) {
+    return seeked;
+  }
+  if (Number.isFinite(lastRequestedStart) && lastRequestedStart > 0) {
+    return lastRequestedStart;
+  }
+  if (Number.isFinite(openedAt) && openedAt > 0) {
+    return openedAt;
+  }
+  return 0;
+}
+
+/**
+ * How far the live boundary table has moved from the one the player holds, said
+ * in words.
+ *
+ * The corrections are applied one boundary at a time and each is small enough
+ * to look harmless; what nobody was watching is the total. It matters because a
+ * run positioned on one table and cut on the other carries their difference into
+ * every cut it makes — the fault of 2026-08-21, where the distance reached two
+ * whole segments after one seek and four after the next. Printed beside each
+ * correction so the total is visible while it is still small.
+ *
+ * @param {number[]} published - The table the playlist text was written from.
+ * @param {number[]} live - The table corrected from produced segments.
+ * @returns {string} A phrase, always readable, never throwing on odd input.
+ */
+export function describeGridDrift(published, live) {
+  if (!Array.isArray(published) || !Array.isArray(live) || published.length === 0) {
+    return "not comparable";
+  }
+  if (published.length !== live.length) {
+    return `a different length (${published.length} against ${live.length})`;
+  }
+  let apart = 0;
+  let worst = 0;
+  let worstAt = -1;
+  for (let index = 0; index < published.length; index += 1) {
+    // Rounded to the millisecond BEFORE comparing, not only before printing.
+    // Two boundaries moved by the same amount differ in the last bits of a
+    // double, so an unrounded comparison picks between them by an accident
+    // invisible in the printed figure — and the line would name a boundary the
+    // reader cannot tell apart from the one before it. Rounded, ties keep the
+    // earliest, which is also the one worth looking at first.
+    const distance = Math.round(Math.abs(live[index] - published[index]) * 1000) / 1000;
+    if (distance <= 0.001) {
+      continue;
+    }
+    apart += 1;
+    if (distance > worst) {
+      worst = distance;
+      worstAt = index;
+    }
+  }
+  if (apart === 0) {
+    return "identical";
+  }
+  return `${apart} of ${published.length} boundaries apart, worst ${worst.toFixed(3)}s at #${worstAt}`;
+}
+
 /**
  * How much later than a keyframe to ASK, so that ffmpeg lands on that keyframe.
  *
@@ -2550,6 +2647,22 @@ export class HlsSessionManager {
       : (session.segmentBoundaries ?? []);
   }
 
+  /**
+   * Where a run beginning at `index` must be positioned: the time the PLAYER
+   * was told that segment starts at.
+   *
+   * Public because it is the invariant this class has broken twice, and a
+   * private one cannot be pinned by a test. It must always be the table the cut
+   * list is taken from — see the comment where a run is started.
+   *
+   * @param {HlsSession} session
+   * @param {number} index
+   * @returns {number}
+   */
+  runStartTimeFor(session, index) {
+    return this.#publishedStartTime(session, index);
+  }
+
   #publishedStartTime(session, index) {
     const boundaries = Array.isArray(session.publishedBoundaries) && session.publishedBoundaries.length > 0
       ? session.publishedBoundaries
@@ -2709,6 +2822,69 @@ export class HlsSessionManager {
     return true;
   }
 
+  /**
+   * Answer the player's report that a delivered fragment sits far from the edge
+   * of its buffer, with the one fact only this side holds: which boundary the
+   * segment of that number really begins at.
+   *
+   * The player can say the gap; it cannot say whether the cause is its own
+   * loading or a run whose output no longer matches its numbering. Here both
+   * are in hand — the time the playlist gave that segment, and, when the
+   * segment has been served, the time it truly began at — so the line either
+   * names a shifted run or clears this side of it.
+   *
+   * Diagnostic only: nothing is repositioned on the strength of a browser's
+   * reading, deliberately, because a wrong answer here would restart an encoder
+   * the viewer is waiting on.
+   *
+   * @param {string} sessionId
+   * @param {{ sn: number, track?: string, fragStartSec: number, bufferEndSec: number, currentTimeSec: number }} report
+   * @returns {boolean} False when no such session exists.
+   */
+  recordFragmentFar(sessionId, { sn, track, fragStartSec, bufferEndSec, currentTimeSec }) {
+    const named = this.sessionsById.get(sessionId);
+    if (!named || named.state === "disposed") {
+      return false;
+    }
+    // Which of the two streams the report is about. The browser addresses
+    // everything to the video session's id — the soundtrack is served under
+    // `/a/<n>/` on that same id — but it is a session of its own, with its own
+    // run and its own position, and that is exactly the pair this report exists
+    // to tell apart. Answering an audio report from the picture's records would
+    // state, confidently, something about the wrong stream.
+    const onScreen = this.#activeVariant(named);
+    const session = track === "audio"
+      ? ([...this.#familyOf(onScreen)].find((member) => member.audioOnly === true) ?? onScreen)
+      : onScreen;
+    const gap = fragStartSec - bufferEndSec;
+    const declared = this.#publishedStartTime(session, sn);
+    const trueStart = session.trueStartByIndex instanceof Map ? session.trueStartByIndex.get(sn) : undefined;
+    const verdict = trueStart === undefined
+      // Where a segment truly began is only ever read off one that was cut on
+      // an explicit list — a uniform grid has nothing to read back — so this is
+      // "not recorded", which is not the same as "not produced", and the line
+      // must not claim the second.
+      ? "where that segment began is not recorded on this side, so the gap cannot be attributed here"
+      : (() => {
+        const at = this.#boundaryIndexAt(session, trueStart, this.publishedGridFor(session));
+        if (at === null) {
+          return `it really began at ${trueStart.toFixed(3)}s, which is no boundary of this grid`;
+        }
+        if (at === sn) {
+          return `it really began at boundary #${sn}, where it should — the gap is not this run's`;
+        }
+        return `it really began at boundary #${at}, ${sn - at} place(s) before its own number — ` +
+          "this run's output does not match its numbering";
+      })();
+    logger.warn(
+      `transcode ${session.id} the player is stuck: ${session.audioOnly === true ? "sound" : "picture"} ` +
+      `fragment #${sn} starts ${gap.toFixed(1)}s past ` +
+      `the end of its buffer (${bufferEndSec.toFixed(1)}s, viewer at ${currentTimeSec.toFixed(1)}s, ` +
+      `the playlist puts it at ${declared.toFixed(3)}s) — ${verdict}`
+    );
+    return true;
+  }
+
   /**
    * Observed produced bitrate (Mbit/s) averaged over the last few COMPLETED
    * segment files (the newest file may still be being written and is
@@ -3756,7 +3932,7 @@ export class HlsSessionManager {
     const head = session.encodeStartIndex;
     const processed = Number.isFinite(session.progress?.processedSeconds)
       ? session.progress.processedSeconds
-      : this.#segmentStartTime(session, head);
+      : this.runStartTimeFor(session, head);
     const currentSeg = Math.max(head, this.#segmentIndexForTime(session, processed));
     const boundLabel =
       bound === "link" ? "viewer-link-bound" : bound === "unknown" ? "assuming CPU-bound" : "CPU-bound";
@@ -3798,9 +3974,18 @@ export class HlsSessionManager {
    *
    * @param {HlsSession} session
    * @param {number} startIndex
+   * @param {number} [positionSecondsOverride] - Begin the run at this instant
+   *   instead of at the time the playlist gives `startIndex`, keeping the
+   *   numbering and the cut list on the published grid. The one caller is the
+   *   realignment below: a COPIED picture cannot cut anywhere but at the
+   *   source's own keyframes, so its segment #N begins where the file says and
+   *   not where the grid does — and the sound that plays with it has to begin
+   *   at that same instant, or the two are apart by the difference. The output
+   *   is still labelled from the source clock (`-copyts`) and stamped on serve,
+   *   so the player sees both at the time the playlist names.
    * @returns {Promise<void>}
    */
-  async #startEncodeRun(session, startIndex) {
+  async #startEncodeRun(session, startIndex, positionSecondsOverride) {
     // A new run starts its own reckoning: a pair spanning the restart would
     // count the gap between two runs as slow encoding.
     session.learnSample = null;
@@ -3899,8 +4084,30 @@ export class HlsSessionManager {
     }
 
     const safeIndex = Number.isInteger(startIndex) && startIndex > 0 ? startIndex : 0;
-    // 0-based output time of this segment, from the boundary table.
-    const startSeconds = this.#segmentStartTime(session, safeIndex);
+    // 0-based output time of this segment, from the table the PLAYER holds —
+    // the same one the cut list below is taken from.
+    //
+    // These two were read from different tables until 2026-08-21, and that is
+    // one fault, not two: `-segment_times` are measured from wherever the run
+    // really began, so any distance between the position and the cut list moves
+    // EVERY cut of that run by it. The live table keeps being corrected as
+    // produced segments reveal where the file's cuts truly are, and those
+    // corrections run backwards, so each restart began a little earlier than
+    // the grid the cuts were stated on — and since the corrections accumulate,
+    // so did the distance. Measured on `JUFD665.mp4`: after one seek restart a
+    // produced segment held the boundary two places before its own number
+    // (16.684 s, exactly 2.0000 segments), after the next it held the one four
+    // places before (33.5 s). The player's buffer then stops extending at all,
+    // because the content of every fragment lands before the time its playlist
+    // entry names: `bufferEnd` stood still at 4571.1 s through four `frag-far`
+    // warnings until hls.js gave up and jumped the viewer 16.8 s forward.
+    //
+    // 2.45.0 moved the CUT LIST onto the published table for this same reason
+    // and left the position on the live one. Both belong on the published
+    // table: a run must begin where the player was told the segment begins.
+    const startSeconds = Number.isFinite(positionSecondsOverride)
+      ? positionSecondsOverride
+      : this.runStartTimeFor(session, safeIndex);
     const sourceStartTime = Number.isFinite(session.sourceStartTime) ? session.sourceStartTime : 0;
     // Cut where this session's grid says, whoever is producing the frames. The
     // times are measured from the start of THIS run; the same list serves as
@@ -4192,6 +4399,17 @@ export class HlsSessionManager {
       `(+${Date.now() - restartEnteredAt}ms since the restart was asked for) ` +
         `(${formatSeconds(startSeconds)}) "${session.fileName}"`
     );
+    // The four numbers a run is positioned by, said once, because their
+    // disagreement is invisible everywhere else. The two tables are printed
+    // side by side: while they differ, every cut of this run is off by the
+    // difference, and nothing downstream can tell that from a bad index.
+    const liveStart = this.#segmentStartTime(session, safeIndex);
+    logger.info(
+      `transcode ${session.id} ${session.runLabel} positioned at ${startSeconds.toFixed(3)}s ` +
+        `for boundary #${safeIndex} (published ${startSeconds.toFixed(3)}s, ` +
+        `live ${liveStart.toFixed(3)}s, apart ${(liveStart - startSeconds).toFixed(3)}s), ` +
+        `numbering from #${safeIndex}`
+    );
 
     this.#wireEncodeProcess(session, ffmpeg);
   }
@@ -4511,7 +4729,7 @@ export class HlsSessionManager {
     // request just ahead of the live edge.
     const processed = Number.isFinite(session.progress?.processedSeconds)
       ? session.progress.processedSeconds
-      : this.#segmentStartTime(session, head);
+      : this.runStartTimeFor(session, head);
     const currentSeg = Math.max(head, this.#segmentIndexForTime(session, processed));
     const withinWindow = index >= head && index <= currentSeg + MAX_LOOKAHEAD_SEGMENTS;
     if (withinWindow) {
@@ -4804,7 +5022,7 @@ export class HlsSessionManager {
     const head = session.encodeStartIndex;
     const processed = Number.isFinite(session.progress?.processedSeconds)
       ? session.progress.processedSeconds
-      : this.#segmentStartTime(session, head);
+      : this.runStartTimeFor(session, head);
     const currentSeg = Math.max(head, this.#segmentIndexForTime(session, processed));
     // Already covered by the running encode — the data is on its way, so
     // restarting would only destroy work the viewer is waiting for. The run has
@@ -5240,7 +5458,17 @@ export class HlsSessionManager {
       return;
     }
     session.landingReportedForRun = index;
-    const asked = this.#segmentStartTime(session, index);
+    // What the run was ASKED for, taken from the run itself rather than looked
+    // up again in a table. The two used to be the same lookup; they stopped
+    // being so when a run began positioning on the published grid while this
+    // read the live one, which made a perfect landing report a drift equal to
+    // the distance between the tables — and cancelled a real landing error of
+    // the same size to zero. A run also has one legitimate position that is in
+    // no table at all: the realignment that starts the sound where the copied
+    // picture truly begins.
+    const asked = Number.isFinite(session.progress?.startPositionSeconds)
+      ? session.progress.startPositionSeconds
+      : this.runStartTimeFor(session, index);
     const drift = trueStart - asked;
     if (!Number.isFinite(drift) || Math.abs(drift) <= PLAYER_BUFFER_HOLE_SEC) {
       return;
@@ -5255,6 +5483,18 @@ export class HlsSessionManager {
   #noteIndexAccuracy(session, index, trueStart, declaredStart) {
     const deviation = Math.abs(trueStart - declaredStart);
     session.indexCheck ??= newIndexCheck();
+    // Where each produced segment truly began, kept so that a player reporting
+    // a stall can be ANSWERED rather than merely believed. Bounded: only the
+    // recent past can be the subject of such a report, and an unbounded map on
+    // a two-hour film is a leak.
+    session.trueStartByIndex ??= new Map();
+    session.trueStartByIndex.set(index, trueStart);
+    if (session.trueStartByIndex.size > TRUE_START_MEMORY) {
+      const oldest = session.trueStartByIndex.keys().next();
+      if (!oldest.done) {
+        session.trueStartByIndex.delete(oldest.value);
+      }
+    }
     // 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
@@ -5299,7 +5539,18 @@ export class HlsSessionManager {
             // rung's segments no longer stand where the stream it accompanies
             // would have put them. That is a broken splice, not a wrong index.
             ? "this rung did not cut where its grid says; a switch to it will not join cleanly"
-            : "the container's keyframe index disagrees with the file; using the file")
+            // A copy. The two possible faults need opposite fixes and the
+            // numbers already tell them apart, so the sentence follows THEM
+            // rather than the branch it is printed from. Until 2026-08-21 it
+            // blamed the index either way — including through a session whose
+            // segments each held the boundary two, then four places before
+            // their own number, which is this code's own definition of a fault
+            // in this code. That sentence is what sent the reading of that
+            // session after the file instead of after the arithmetic.
+            : at === null
+              ? "the container's keyframe index disagrees with the file; using the file"
+              : `this began at another boundary of the same list, ${index - at} place(s) before ` +
+                "its own number — the numbering of this run is shifted, not the index")
         );
       }
     }
@@ -5382,7 +5633,9 @@ export class HlsSessionManager {
     }
     logger.info(
       `transcode ${session.id} boundary #${index} corrected ${wasAt.toFixed(3)}s → ` +
-      `${trueStart.toFixed(3)}s from the file itself`
+      `${trueStart.toFixed(3)}s from the file itself` +
+      `, and the live table is now ${describeGridDrift(this.publishedGridFor(session), boundaries)}` +
+      " from the one the player holds"
     );
     // And every OTHER member whose run begins at this very boundary is moved
     // to the same instant.
@@ -5418,9 +5671,18 @@ export class HlsSessionManager {
       // time: a seek decides by index, finds this run already begins at #index,
       // and answers "already within the running encode" — which is true about
       // the index and false about the instant, and it is why the first version
-      // of this fix moved nothing at all. The boundary now holds the corrected
-      // time, so starting the run at this index starts it at that time.
-      void this.#startEncodeRun(member, index).catch(() => {});
+      // of this fix moved nothing at all.
+      //
+      // The instant is passed EXPLICITLY. It used to be smuggled through the
+      // live boundary table — this function had just written `trueStart` into
+      // it, and the run read its position from there — which stopped working
+      // the moment a run began positioning itself on the table the player
+      // holds, as it now must. Smuggled, the restart would land exactly where
+      // it already was: picture and sound would stay apart and a healthy audio
+      // run would be discarded for nothing, which is the shape the field
+      // already showed (eleven restarts in four minutes, eight of them dying
+      // with `run had produced 0.0s`).
+      void this.#startEncodeRun(member, index, trueStart).catch(() => {});
     }
   }
 
@@ -5503,8 +5765,14 @@ export class HlsSessionManager {
    * @param {number} seconds
    * @returns {number | null}
    */
-  #boundaryIndexAt(session, seconds) {
-    const boundaries = session.segmentBoundaries;
+  #boundaryIndexAt(session, seconds, table) {
+    // The table is nameable because the two answer different questions. The
+    // LIVE one says "is this a cut this file actually has", which is what a
+    // reading taken off a produced segment is about. The PUBLISHED one says "is
+    // this a cut the player believes in", which is what a report from the player
+    // is about. Answering one with the other prints an index from one grid
+    // beside a time from the other.
+    const boundaries = Array.isArray(table) ? table : session.segmentBoundaries;
     if (!Array.isArray(boundaries)) {
       return null;
     }
@@ -6702,13 +6970,14 @@ export class HlsSessionManager {
   }
 
   #viewerPositionOf(session) {
-    if (Number.isFinite(session.viewerPositionSeconds) && session.viewerPositionSeconds > 0) {
-      return session.viewerPositionSeconds;
-    }
-    if (Number.isInteger(session.lastRequestedSegment) && session.lastRequestedSegment > 0) {
-      return this.#segmentStartTime(session, session.lastRequestedSegment);
-    }
-    return 0;
+    const lastRequestedStart = Number.isInteger(session.lastRequestedSegment) && session.lastRequestedSegment > 0
+      ? this.#segmentStartTime(session, session.lastRequestedSegment)
+      : null;
+    return resolveViewerPosition({
+      seeked: session.viewerPositionSeconds,
+      lastRequestedStart,
+      openedAt: session.progress?.startPositionSeconds
+    });
   }
 
   /**
@@ -7985,7 +8254,14 @@ export class HlsSessionManager {
     // causes indistinguishable: an encoder waiting for torrent pieces looks
     // exactly like one that is encoding and simply has not finished. The
     // difference is whether its position has moved at all.
-    const runStartSeconds = this.#segmentStartTime(session, session.encodeStartIndex ?? 0);
+    // Where this run began, from the run — the same reckoning
+    // `processedSeconds` is counted in. A table lookup here can disagree with
+    // it by the distance between the two grids, which is enough to print a
+    // negative "produced" and send the reader after the torrent when the
+    // encoder is the subject.
+    const runStartSeconds = Number.isFinite(session.progress?.startPositionSeconds)
+      ? session.progress.startPositionSeconds
+      : this.runStartTimeFor(session, session.encodeStartIndex ?? 0);
     const position = Number(session.progress?.processedSeconds);
     const produced = Number.isFinite(position) ? position - runStartSeconds : null;
     const speed = session.progress?.speed ?? "n/a";