@torrent-tv/proxy 2.48.0 → 2.50.0

package/CHANGELOG.md

@@ -1,3 +1,14 @@
+## 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.
+- **Fix**: A container with no keyframe index is re-encoded rather than copied against a grid nobody knows. MPEG-TS carries no index of any kind — measured the same day, 669 real keyframes and nothing to read them from without walking the file — and a copied picture can only be cut at the source's own keyframes, so declaring an even grid is a falsehood the player punishes: it walks the whole file to rebuild the timeline, or presents audio with no picture because a segment begins with nothing decodable, both field-observed 2026-08-02. Re-encoding PLACES keyframes on our own cuts, so the grid is right by construction whatever the container. A container whose index could not be read inside the budget lands here too, for the same reason. It costs an encoder, and the alternative was a broken playlist.
+
+## 2.49.0
+
+- **Fix**: The torrent worker is allowed to END rather than being torn down under itself. A core dump read on 2026-08-21 named the fault the proxy has been dying of: `SIGSEGV` in `v8::Value::IsArrayBufferView` reached through `napi_get_buffer_info` from utp-native's `on_utp_accept`, called from its UDP read — all of it inside `node::Environment::CleanupHandles`, under `FreeEnvironment`, on `Worker::Run`. That is a teardown race, not a data fault, which is why neither patch our forked library already carries touched it: a datagram arriving while the environment is being freed walks into an isolate that no longer exists. `destroyAll` called `Worker.terminate()` immediately after destroying the client inside, and `terminate()` frees the environment with libuv's handle callbacks still queued. It now waits for the thread to exit by itself — once the client is destroyed nothing holds its loop open — with `terminate()` kept as a five-second fallback, because a shutdown that hangs is worse than one that is forced.
+- **New**: A worker thread that ends is noticed. Only `message` and `error` were listened for, so when the thread went away the proxy simply stopped and the log ended mid-sentence — five times in three days with not one line to say so, and no way to tell our own shutdown from the thread dying. An `exit` handler now says which of the two it was, and fails everything waiting rather than leaving it hanging.
+- **New**: Core dumps are capped at the newest two at startup. Each is the worker's whole address space — 4.18 GB on the field host — and four of them had nearly filled a 235 GB disk. The newest stay because they are the evidence for the fault still open. `dumpsToRemove` is pure and tested.
+
 ## 2.48.0
 
 - **Fix**: A copied picture now begins where it was asked to, so its cuts land on the times its playlist names. ffmpeg's own CLI moves an input seek back by `3*AV_TIME_BASE / 23` — **130.435 ms** — whenever the container does not declare `AVFMT_SEEK_TO_PTS` (Matroska does not) and a stream carries B-frames, which is sound in itself: such containers seek in decode order while the caller asks in presentation order. The consequence for a copy is that asking for a keyframe lands on the one BEFORE it, deterministically; and since `-segment_times` is measured from where the run really began while this code computed those offsets from the time it asked for, every cut of the run inherited one whole keyframe interval. Field 2026-08-20: 119 of 125 segments arriving a uniform 2.002 s early against the 0.5 s hls.js bridges, so every fragment was refused and re-fetched — on 2026-08-17 two of them 1908 times each. The request is now made that much later, bounded by half the distance to the next keyframe. Measured 2026-08-21 on Matroska with keyframes every 2 s: `-ss 10` produced a first segment starting at 8.000, `-ss 10.130435` one starting at 10.000; on MP4, where the heuristic does not fire, 10, 10.130435 and 10.2 all produced 10.000 — right in one case and harmless in the other. Not applied when the picture is re-encoded: a re-encode discards frames up to the requested time and already begins exactly there (`-ss 11` copied starts at 10.000, re-encoded at 11.000).

package/bin/cli.js

@@ -23,6 +23,7 @@ import { registerClient } from "../services/registry-api.js";
 import { createTunnelClient } from "../services/tunnel-client.js";
 import { createWebRtcManager } from "../services/webrtc-manager.js";
 import { createDataChannelHandler } from "../services/data-channel-handler.js";
+import { pruneCoreDumps } from "../services/core-dumps.js";
 import { collectHealthMetrics } from "../services/health-collector.js";
 import { createPortMapper } from "../services/port-mapper.js";
 import { classifyNat } from "../services/nat-classifier.js";
@@ -294,6 +295,11 @@ try {
   actualPort = started.port;
   const directBaseUrl = explicitBaseUrl || `http://${bindHost}:${actualPort}`;
 
+  // A native fault writes the whole address space out — 4.18 GB each on the
+  // field host, and four of them nearly filled a 235 GB disk. Keep the newest
+  // two, which are the evidence for the fault still open, and drop the rest.
+  void pruneCoreDumps(options.stateDir);
+
   logger.info(`Starting @torrent-tv/proxy v${PROXY_VERSION}`);
   logger.info(`Local stream endpoint: http://${bindHost}:${actualPort}/stream`);
   logger.info(`Advertised direct URL: ${directBaseUrl}`);

package/package.json

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

package/services/container-index/avi.js

@@ -152,5 +152,16 @@ export async function readAviKeyframeTimes(readRange, fileSize) {
     }
     videoFrame += 1;
   }
-  return times.length > 0 ? times : null;
+  if (times.length === 0) {
+    return null;
+  }
+  // AVI names a keyframe by its FRAME NUMBER, and the time above is that number
+  // multiplied by the frame duration the header declares. The frames are the
+  // right ones — measured 2026-08-21 against the files themselves, 1196 index
+  // entries against 1196 real keyframes and 901 against 901, exactly — but the
+  // names are 10-44 ms away from the presentation times the demuxer computes,
+  // always under one frame. So the caller is told how far a time here may be
+  // from the instant it refers to, and can ask for a seek late enough that it
+  // still lands on the frame rather than on the one before it.
+  return { times, tolerance: secondsPerFrame };
 }

package/services/container-index/index.js

@@ -62,7 +62,7 @@ const READERS = [
  * @param {ReadRange} params.readRange
  * @param {number} params.fileSize
  * @param {string} [params.label] - For logging only.
- * @returns {Promise<{ times: number[] | null, format: string }>} Ascending
+ * @returns {Promise<{ times: number[] | null, format: string, tolerance: number }>} Ascending
  *   seconds, or null times when this file has no readable index — the caller
  *   must then not claim to know the grid. The format is which reader matched,
  *   reported whether or not it produced anything: how often an index disagrees
@@ -71,27 +71,39 @@ const READERS = [
  */
 export async function readKeyframeIndex({ readRange, fileSize, label = "" }) {
   if (typeof readRange !== "function" || !Number.isFinite(fileSize) || fileSize <= 0) {
-    return { times: null, format: "unknown" };
+    return { times: null, format: "unknown", tolerance: 0 };
   }
 
   const startedAt = Date.now();
   let times = null;
   let format = "unrecognised";
+  // How far a time in `times` may be from the instant it names. Zero wherever
+  // the container states instants outright, which Matroska and MP4 both do.
+  let tolerance = 0;
   try {
     const sniff = await readRange(0, Math.min(SNIFF_BYTES - 1, fileSize - 1));
     if (!sniff) {
-      return { times: null, format: "unread" };
+      return { times: null, format: "unread", tolerance: 0 };
     }
     const reader = READERS.find((candidate) => candidate.matches(sniff));
     if (reader) {
       format = reader.name;
-      times = await reader.read(readRange, fileSize);
+      const read = await reader.read(readRange, fileSize);
+      // A reader may answer with the times alone, or with how far those times
+      // may sit from the instants they name — which only AVI has to say,
+      // because only AVI computes them from frame numbers.
+      if (Array.isArray(read)) {
+        times = read;
+      } else if (read && Array.isArray(read.times)) {
+        times = read.times;
+        tolerance = Number.isFinite(read.tolerance) ? read.tolerance : 0;
+      }
     }
   } catch (error) {
     // A malformed or partially-downloaded index must never take playback down —
     // it only means the grid is unknown, which the caller already handles.
     logger.warn(`container-index: failed to read index for "${label}": ${error?.message ?? error}`);
-    return { times: null, format };
+    return { times: null, format, tolerance: 0 };
   }
 
   const elapsedMs = Date.now() - startedAt;
@@ -102,5 +114,5 @@ export async function readKeyframeIndex({ readRange, fileSize, label = "" }) {
   } else {
     logger.info(`container-index: no usable index for "${label}" (${format}, ${elapsedMs}ms)`);
   }
-  return { times, format };
+  return { times, format, tolerance };
 }

package/services/core-dumps.js

@@ -0,0 +1,106 @@
+/**
+ * @file Keep the last few core dumps and no more.
+ *
+ * A native fault on the torrent worker writes the whole address space out: on
+ * the field host that is **4.18 GB each**, and four of them had nearly filled a
+ * 235 GB disk by 2026-08-21. The dumps are worth having — the one read that day
+ * named a fault three days of reasoning had not — but only the recent ones are,
+ * and a full disk costs more than an old dump is worth.
+ *
+ * Deliberately not "delete them all": the newest are the evidence for the fault
+ * that is still open (roadmap item 7).
+ */
+
+import { readdir, rm, stat } from "node:fs/promises";
+import path from "node:path";
+
+import { logger } from "../utils/logger.js";
+
+/** How many to keep, newest first. */
+export const CORE_DUMPS_KEPT = 2;
+
+/**
+ * Which dumps to remove, given what is there.
+ *
+ * Pure, so the rule can be tested without a filesystem: newest first by the
+ * time they were written, keep `keep`, name the rest.
+ *
+ * @param {Array<{ name: string, writtenAt: number }>} dumps
+ * @param {number} [keep]
+ * @returns {string[]} Names to delete, oldest first.
+ */
+export function dumpsToRemove(dumps, keep = CORE_DUMPS_KEPT) {
+  const sorted = [...(Array.isArray(dumps) ? dumps : [])]
+    .filter((dump) => typeof dump?.name === "string" && Number.isFinite(dump?.writtenAt))
+    .sort((left, right) => right.writtenAt - left.writtenAt);
+  return sorted.slice(Math.max(0, keep)).map((dump) => dump.name).reverse();
+}
+
+/**
+ * Whether a file name is a core dump this host wrote.
+ *
+ * The kernel's pattern on the addon host produces `core.<thread>.<pid>.<epoch>`
+ * — every one seen so far is `core.WorkerThread.81.…`, the thread the torrent
+ * client runs on. Matched loosely on the `core.` prefix so a differently
+ * configured host is still swept.
+ *
+ * @param {string} name
+ * @returns {boolean}
+ */
+export function isCoreDump(name) {
+  return typeof name === "string" && /^core\.[^/\\]+$/.test(name);
+}
+
+/**
+ * Delete all but the newest few core dumps in `dir`.
+ *
+ * Best-effort and never fatal: a proxy that cannot tidy its dumps still has to
+ * serve video.
+ *
+ * @param {string} dir
+ * @param {number} [keep]
+ * @returns {Promise<void>}
+ */
+export async function pruneCoreDumps(dir, keep = CORE_DUMPS_KEPT) {
+  if (typeof dir !== "string" || dir.length === 0) {
+    return;
+  }
+  /** @type {Array<{ name: string, writtenAt: number, bytes: number }>} */
+  const dumps = [];
+  try {
+    for (const name of await readdir(dir)) {
+      if (!isCoreDump(name)) {
+        continue;
+      }
+      try {
+        const info = await stat(path.join(dir, name));
+        if (info.isFile()) {
+          dumps.push({ name, writtenAt: info.mtimeMs, bytes: info.size });
+        }
+      } catch {
+        // silent-ok: it went away between listing and reading, which is the
+        // outcome this function wanted anyway.
+      }
+    }
+  } catch {
+    return; // No such directory, or unreadable. Nothing to tidy.
+  }
+  if (dumps.length === 0) {
+    return;
+  }
+  const doomed = dumpsToRemove(dumps, keep);
+  const freed = dumps
+    .filter((dump) => doomed.includes(dump.name))
+    .reduce((total, dump) => total + dump.bytes, 0);
+  for (const name of doomed) {
+    try {
+      await rm(path.join(dir, name), { force: true });
+    } catch {
+      // silent-ok: best effort, and the next start tries again.
+    }
+  }
+  logger.info(
+    `core dumps: ${dumps.length} present, keeping the newest ${Math.min(keep, dumps.length)}` +
+      (doomed.length > 0 ? `, removed ${doomed.length} (${(freed / 1e9).toFixed(2)} GB)` : "")
+  );
+}

package/services/hls-session-manager.js

@@ -1196,12 +1196,17 @@ export function seekLandingOffsetFor(session, keyframe) {
   if (session?.transcodeVideo === true) {
     return 0;
   }
+  // A grid whose times are approximate needs that error added on top, or a name
+  // sitting just below its real keyframe seeks to before it and lands on the
+  // one before that. Only AVI declares one.
+  const tolerance = Number.isFinite(session?.keyframeTolerance) ? Math.max(0, session.keyframeTolerance) : 0;
+  const wanted = SEEK_LANDING_OFFSET_SEC + tolerance;
   const times = Array.isArray(session?.keyframeTimes) ? session.keyframeTimes : [];
   const next = times.find((time) => time > keyframe + 0.001);
   if (next === undefined) {
-    return SEEK_LANDING_OFFSET_SEC;
+    return wanted;
   }
-  return Math.min(SEEK_LANDING_OFFSET_SEC, (next - keyframe) / 2);
+  return Math.min(wanted, (next - keyframe) / 2);
 }
 
 /**
@@ -1746,6 +1751,13 @@ export class HlsSessionManager {
     // branches; on failure both fall back to their current behaviour (uniform
     // grid for boundaries, raw target for seeking) — no regression.
     let keyframeTimes = null;
+    // How far a time in `keyframeTimes` may sit from the instant it names. Only
+    // AVI has anything to declare here: it stores frame NUMBERS and the time is
+    // that number times the frame duration, which lands 10-44 ms from the
+    // presentation time the demuxer computes (measured 2026-08-21). A seek made
+    // at such a name can fall just BELOW the real keyframe and land on the one
+    // before it, which is the same fault the landing offset exists for.
+    let keyframeTolerance = 0;
     let keyframeMs = -1; // -1 = not run (skipped), -2 = running in the background
     // Which container supplied the index, carried so the accuracy summary can
     // say what it is a summary OF.
@@ -1758,6 +1770,9 @@ export class HlsSessionManager {
     if (inheritedGrid) {
       keyframeTimes = inheritedGrid.keyframeTimes;
       containerFormat = inheritedGrid.containerFormat ?? "";
+      keyframeTolerance = Number.isFinite(inheritedGrid.keyframeTolerance)
+        ? inheritedGrid.keyframeTolerance
+        : 0;
     } else if (hasDuration && !transcodeVideo && !audioOnly) {
       // Video-COPY path: keyframeTimes are REQUIRED to build correct segment
       // boundaries (the playlist itself), so this MUST block session creation —
@@ -1779,11 +1794,28 @@ export class HlsSessionManager {
       const index = await this.#readContainerKeyframes({ sourceKey, fileIndex, inputUrl, logName });
       keyframeTimes = index.times;
       containerFormat = index.format;
+      keyframeTolerance = Number.isFinite(index.tolerance) ? index.tolerance : 0;
       keyframeMs = Date.now() - keyframeStartMs;
       if (!keyframeTimes) {
+        // No index, so there is no honest grid for a COPY: a copied picture can
+        // only be cut at the source's own keyframes, and we do not know where
+        // they are. Declaring an even grid instead is a falsehood the player
+        // punishes — it walks the whole file to rebuild the timeline, or shows
+        // audio with no picture because a segment begins with nothing
+        // decodable (both field-observed 2026-08-02).
+        //
+        // Re-encoding is the honest answer and costs an encoder: keyframes are
+        // then PLACED at our own cut times rather than found, so the grid is
+        // correct by construction whatever the container. MPEG-TS is the case
+        // this exists for — measured 2026-08-21, 669 real keyframes and no
+        // index of any kind to read them from — and a container whose index
+        // could not be read in the budget lands here too, which is right for
+        // the same reason.
+        transcodeVideo = true;
         logger.warn(
-          `transcode ${sessionId}: no container keyframe index for "${logName}"; ` +
-            `falling back to a uniform grid — segment boundaries will not match the media`
+          `transcode ${sessionId}: no keyframe index in the ${containerFormat} container for ` +
+            `"${logName}" — a copied picture has no honest grid without one, so the video is ` +
+            "re-encoded instead and its keyframes are placed on our own cuts"
         );
       }
     } else if (hasDuration && transcodeVideo) {
@@ -2035,6 +2067,9 @@ export class HlsSessionManager {
       // KNOWN valid position instead of trusting the container's own on-the-fly
       // seek at an arbitrary target — see the probe call above for why.
       keyframeTimes,
+      // How far those times may sit from the instants they name — nonzero only
+      // for AVI, which computes them from frame numbers.
+      keyframeTolerance,
       // Which container the index came from, and how well it has held up. The
       // cut times of a copied video ARE its index, and an index can be wrong —
       // measured 2026-08-06, one claimed a keyframe four seconds from where the
@@ -6848,6 +6883,7 @@ export class HlsSessionManager {
             // creations (field 2026-08-17, corrections of 0.6-2.9 s).
             published: base.publishedBoundaries,
             keyframeTimes: base.keyframeTimes,
+            keyframeTolerance: base.keyframeTolerance,
             containerFormat: base.containerFormat
           }
         : null,

package/services/torrent-worker/client.js

@@ -22,6 +22,15 @@ import { createCaller, createReceiveStream } from "./channel.js";
 import { Command, Event } from "./protocol.js";
 
 const WORKER_URL = new URL("./worker.js", import.meta.url);
+/**
+ * How long a shutdown waits for the thread to end by itself before forcing it.
+ *
+ * Ending by itself is what lets libuv drain the handle callbacks it is holding;
+ * forcing it is what ran one of those against a freed isolate. Five seconds is
+ * long enough for a destroyed torrent client to release its sockets and short
+ * enough that a shutdown never appears to hang.
+ */
+const WORKER_EXIT_GRACE_MS = 5_000;
 
 /**
  * Runs the torrent client on its own thread and exposes it to the main thread.
@@ -34,6 +43,12 @@ const WORKER_URL = new URL("./worker.js", import.meta.url);
  */
 export class TorrentWorkerClient {
   #worker;
+  /**
+   * Whether this shutdown was asked for, so the thread ending can be told from
+   * the thread dying. Without it both look identical from outside, which is how
+   * five crashes produced no line in the log.
+   */
+  #stopping = false;
   #caller;
   /** Receive-side handles for in-flight reads, keyed by request id. */
   #reads = new Map();
@@ -186,6 +201,30 @@ export class TorrentWorkerClient {
       }
       this.#reads.clear();
     });
+
+    // A worker that ENDS was, until now, not noticed at all: only `message` and
+    // `error` were listened for. So when the thread went away the proxy simply
+    // stopped, the log ended mid-sentence, and nothing said whether we had
+    // asked for it — which is precisely the reading that was missing on
+    // 2026-08-21, when a core dump showed the thread faulting inside
+    // `Environment::CleanupHandles` and there was no way to tell our own
+    // shutdown from the thread ending on its own.
+    this.#worker.on("exit", (code) => {
+      if (this.#stopping) {
+        logger.info(`torrent-worker: thread ended as asked (code ${code})`);
+        return;
+      }
+      logger.error(
+        `torrent-worker: thread ended on its own with code ${code} — nobody asked it to. ` +
+        "Everything waiting on it is failed; the proxy has no torrent client until it is rebuilt."
+      );
+      const reason = new Error("Torrent worker ended unexpectedly.");
+      this.#caller.rejectAll(reason);
+      for (const [, read] of this.#reads) {
+        read.fail(reason);
+      }
+      this.#reads.clear();
+    });
   }
 
   /**
@@ -520,11 +559,33 @@ export class TorrentWorkerClient {
    * @returns {Promise<void>}
    */
   async destroyAll() {
+    this.#stopping = true;
     try {
       await this.#caller.call(Command.DESTROY_ALL, {});
     } catch {
-      // Already gone — termination below is what matters.
+      // Already gone — the wait below settles either way.
     }
-    await this.#worker.terminate();
+    // Let the thread END rather than tearing it down under itself.
+    //
+    // `terminate()` frees the environment immediately, with the handle
+    // callbacks libuv still holds queued. One of those is utp-native's UDP
+    // read, and running it against a freed isolate is what the core dump of
+    // 2026-08-21 caught: `on_utp_accept` → `napi_get_buffer_info` →
+    // `v8::Value::IsArrayBufferView` inside `Environment::CleanupHandles`.
+    // Once the client inside is destroyed the thread has nothing left holding
+    // its loop open, so it exits by itself and the callbacks drain first.
+    //
+    // `terminate()` stays as the bounded fallback, because a shutdown that
+    // hangs is worse than one that is forced.
+    await new Promise((resolve) => {
+      const timer = setTimeout(() => {
+        logger.warn("torrent-worker: thread did not end in 5s; terminating it");
+        void this.#worker.terminate().finally(resolve);
+      }, WORKER_EXIT_GRACE_MS);
+      this.#worker.once("exit", () => {
+        clearTimeout(timer);
+        resolve();
+      });
+    });
   }
 }

package/test/core-dumps.test.js

@@ -0,0 +1,57 @@
+/**
+ * @file Keep the last few core dumps and no more.
+ *
+ * Each is the worker thread's whole address space — 4.18 GB on the field host —
+ * and four of them had nearly filled a 235 GB disk by 2026-08-21. The newest
+ * are evidence for a fault that is still open, so they stay; the rest go.
+ */
+
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { dumpsToRemove, isCoreDump } from "../services/core-dumps.js";
+
+const dumps = [
+  { name: "core.WorkerThread.81.1787176646", writtenAt: 1787176646000 },
+  { name: "core.WorkerThread.81.1787224562", writtenAt: 1787224562000 },
+  { name: "core.WorkerThread.81.1787237468", writtenAt: 1787237468000 },
+  { name: "core.WorkerThread.81.1787243278", writtenAt: 1787243278000 },
+  { name: "core.WorkerThread.81.1787292750", writtenAt: 1787292750000 }
+];
+
+test("the newest two stay and the rest go, oldest first", () => {
+  assert.deepEqual(dumpsToRemove(dumps), [
+    "core.WorkerThread.81.1787176646",
+    "core.WorkerThread.81.1787224562",
+    "core.WorkerThread.81.1787237468"
+  ]);
+});
+
+test("fewer than the limit leaves everything alone", () => {
+  assert.deepEqual(dumpsToRemove(dumps.slice(0, 2)), []);
+  assert.deepEqual(dumpsToRemove([]), []);
+});
+
+test("order on disk does not decide; the time written does", () => {
+  const shuffled = [dumps[3], dumps[0], dumps[4], dumps[2], dumps[1]];
+  assert.deepEqual(dumpsToRemove(shuffled, 1), [
+    "core.WorkerThread.81.1787176646",
+    "core.WorkerThread.81.1787224562",
+    "core.WorkerThread.81.1787237468",
+    "core.WorkerThread.81.1787243278"
+  ]);
+});
+
+test("only core dumps are considered", () => {
+  assert.equal(isCoreDump("core.WorkerThread.81.1787292750"), true);
+  assert.equal(isCoreDump("proxy.log"), false);
+  assert.equal(isCoreDump("host-timings.json"), false);
+  // Not a path, and not a directory called core.
+  assert.equal(isCoreDump("core.foo/bar"), false);
+  assert.equal(isCoreDump(""), false);
+});
+
+test("nothing readable is not a reason to delete anything", () => {
+  assert.deepEqual(dumpsToRemove(null), []);
+  assert.deepEqual(dumpsToRemove([{ name: 5, writtenAt: "x" }]), []);
+});

package/test/seek-landing.test.js

@@ -48,3 +48,29 @@ test("no keyframe list is still answered", () => {
   assert.equal(seekLandingOffsetFor({ transcodeVideo: false }, 5), OFFSET);
   assert.equal(seekLandingOffsetFor(null, 5), OFFSET);
 });
+
+test("a grid whose times are approximate is asked for that much later again", () => {
+  // AVI names a keyframe by its frame NUMBER and the time is that number times
+  // the frame duration, so a name can sit just BELOW the keyframe it refers to
+  // — measured 2026-08-21, 10-44 ms out on two files, always under one frame.
+  // Asking at the name alone would seek to before the real keyframe and land on
+  // the one before that, which is the fault this offset exists for.
+  const session = {
+    transcodeVideo: false,
+    keyframeTolerance: 0.04,
+    keyframeTimes: [0, 4.004, 8.008, 12.012]
+  };
+  assert.equal(seekLandingOffsetFor(session, 4.004), OFFSET + 0.04);
+});
+
+test("an exact grid claims no tolerance", () => {
+  // Matroska and MP4 state instants outright — measured the same day, nine
+  // files and 11 665 keyframes with not one disagreement.
+  const session = { transcodeVideo: false, keyframeTolerance: 0, keyframeTimes: [0, 4.004, 8.008] };
+  assert.equal(seekLandingOffsetFor(session, 4.004), OFFSET);
+});
+
+test("the bound still holds once a tolerance is added", () => {
+  const session = { transcodeVideo: false, keyframeTolerance: 1, keyframeTimes: [0, 0.1, 0.2] };
+  assert.equal(seekLandingOffsetFor(session, 0.1), 0.05);
+});