@torrent-tv/proxy 2.83.8 → 2.84.0

package/CHANGELOG.md

@@ -1,3 +1,13 @@
+## 2.84.0
+
+- **Fix**: WHERE A VIEWER IS HAS ONE WRITER AND IS A FUNCTION OF TIME. It had two: a seek wrote `position.seeked`, a segment request overwrote `position.seconds`, and the reading preferred whichever was set — so the two took turns and the priority map jumped backwards and forwards several times a second. Field 2026-09-13, one output over one second: `p100:#9..#10`, `p100:#18..#20`, `p100:#16..#18`, `p100:#18..#20`, with the second viewer stopped dead at 1673.6 s throughout. Encoder placement follows the map, as it must, so the machine spent six minutes on **77 starts and 141 stops against one normal end**, produced almost nothing, and both browsers sat frozen with empty buffers while the swarm delivered 3 MB/s from 129 peers. A segment request now says only that the viewer is still here; where they are is what they state, and between statements it is carried forward by the clock at the rate the film moves — `position(now) = stated + (playing ? 1 : 0) × (now − statedAt)`. Continuous and monotone by construction, so nothing derived from it can dither.
+- **Fix**: A picture starved of data is no longer reported as moving. `paused` is false while an element waits for bytes, so a frozen player told the proxy it was playing and the position walked away from where the viewer actually stood — the exact case a frozen player is in. It is `readyState >= HAVE_FUTURE_DATA` as well now, and `waiting` joins `pause`/`playing`/`ended` in the events that report at once rather than waiting out the ten-second interval.
+- **Fix**: PRESENCE IS THE CONNECTION AND ONLY THE CONNECTION. Silence longer than "any silence a watching viewer can produce" used to end it, and there is no such interval: a paused viewer, a hidden tab whose timers the browser has throttled, and one holding two minutes of cushion all say nothing and are all still watching. A viewer is here until something says otherwise — the browser releasing the session, or the connection closing. `presenceStaleAfterMs` and every threshold it fed are gone.
+- **Fix**: A soundtrack begins where the earliest viewer of the picture stands, with nothing subtracted. What that replaced was an apparatus for turning a request edge back into a playhead: three position sources ranked by priority, a second function naming which had answered, a subtraction of the deepest reported buffer, and a special case for a session nobody had asked anything of yet. Each repaired a quantity that meant two things. Field 2026-08-31, what it cost: a page opened at 588 s started its sound at 460 s — 131 seconds of film nobody would hear, and the segment the viewer needed took 38.8 s against the picture's 8.4 s.
+- **Chore**: `resolveViewerPosition`, `viewerPositionSource`, `#viewerPositionSourceOf`, `#consumerPositionOf`, `#noteConsumerHead`, `session.lastRequestedSegment`, `session.furthestViewerSeconds` and `headsOf` are deleted. Where a viewer is now lives in the viewer's own layer (`viewer/positions.js`), and the session manager is 250 lines shorter for it.
+- **Chore**: The flag that pins a rung's size is `exactSize`, not `manualQuality`, and the key it writes reads `enc:1280x720:exact` rather than `:manual`. It says nothing about who asked — every rung of a master sets it, whether the viewer picked that rung or the player moved itself onto one — and the old name was read as "the viewer did this" four times in a few weeks, in field logs where the viewer had touched nothing. The log line says `size=exact` for the same reason. Requires server 0.27.14 or newer in the page.
+- **New**: `test/plan-is-steady.test.js` — five checks that the placement does not move while the facts do not, over the whole chain from what a viewer states to what the plan answers, with the field's own two positions. Confirmed to go red on the reading this release replaced.
+
 ## 2.83.8
 
 - **New**: THE BROWSER'S OWN LOG IS KEPT BESIDE THE PROXY'S, ON A DISK THAT SURVIVES. Explaining any failure here needs both halves — what the proxy did and what the page saw — and the second half went to the registry server's standard output on the droplet, which every release of it destroys. On 2026-09-13 a viewer reported a desync and a frozen picture and the analysis ran on half the evidence for exactly that reason. `POST /api/client-logs` on the proxy writes them into the same directory as its own log (`/data` on the addon host), one file per viewing session: `client-<start>-<session>-<film>-<infohash>.log`. The start time and the session id are what join the two halves without guessing, and the film says which one it is without opening the file. Seven checks over the writer, one confirmed to go red.

package/CLAUDE.md

@@ -89,9 +89,11 @@ Linux-only host (e.g. POSIX-only signals must degrade elsewhere).
     why the priority map is read at two scopes (per FILE for the swarm, per
     OUTPUT for the encoders), and what each of the eight other places that used
     to place or kill an encoder now states instead.
-  - `docs/logs.md` — where to find logs (HA `docker logs` + `/data/proxy.log`, DO
-    `infra-server-1` with forwarded frontend `POST /api/client-logs`). Browser
-    console not needed.
+  - `docs/logs.md` — where to find logs, and the fact that the BROWSER's own log
+    is in TWO places split by phase: on the droplet while a transport is being
+    acquired and at unload, on THIS proxy for the whole of a viewing
+    (`/data/client-<start>-<session>-<torrent>.log`, one file per session).
+    Read both before concluding anything from a half-session.
   - `playback-planner.js` — single ffmpeg probe returns audioCodec, videoCodec,
     container, durationSeconds. `mode` is advisory; the browser decides.
   - `hls-session-manager.js` — one ffmpeg per (source, file, settings). Serves a

package/docs/encode-architecture.md

@@ -28,12 +28,37 @@ It decides from four things and no others:
 name a consumer id, or hold a person. What crosses is a priority map: zones of
 segment numbers with a rank and a real time, and nobody's name on it.
 
+## Where a viewer is, and how it reaches the encoders
+
+A viewer's position has ONE writer — the viewer — and is a function of time:
+
+```
+position(now) = stated + (playing ? 1 : 0) × (now − statedAt)
+```
+
+A viewer whose picture moves covers a second of film every second, so between
+the moments they speak their position is known exactly; one whose picture is
+stopped covers nothing. Nothing else writes it, and in particular a request for
+a segment does not: a request says the viewer is still here, and the segment
+either exists and is served or does not and is waited for.
+
+Held as a stored number instead it was a staircase, flat for the ten seconds
+between reports and then a jump — and with two writers filling it in turn the
+steps went backwards as often as forwards. Field 2026-09-13, one output over one
+second: `p100:#9..#10`, `p100:#18..#20`, `p100:#16..#18`, `p100:#18..#20`, while
+the second viewer sat frozen at 1673.6 s. The placement follows the map, so the
+machine spent six minutes on 77 encoder starts and 141 stops.
+
+PRESENCE IS A SEPARATE FACT and it is the connection: a viewer is here until
+something says otherwise. Silence never says it — a pause, a hidden tab whose
+timers are throttled, and a full cushion are all silent and all still watching.
+
 ## Viewers become a map, and that is the whole crossing
 
 ```mermaid
 flowchart TB
   subgraph V["services/viewer — where people are"]
-    VW[Viewer<br/>position, playing, buffered, chosen track]
+    VW[Viewer<br/>position as a function of time, playing, buffered, chosen track]
     VS[Viewers<br/>the relation, indexed from both ends]
   end
 

package/docs/logs.md

@@ -1,51 +1,97 @@
-# Logs — where to look
-
-All logs are visible via container `docker logs`, no browser console copy-paste needed.
-
-## HA proxy (aarch64, addon `b34a1737_torrent_tv_proxy`)
-
-Image `b34a1737/aarch64-addon-torrent_tv_proxy:<version>` = `@torrent-tv/proxy` `<version>` (see `ha-addon/torrent_tv_proxy/config.yaml`).
-
-- Console + file are the same: the proxy logs to both `stdout` and `/data/proxy.log` on start (`logging to /data/proxy.log as well as the console`).
-- **Since 2.71.0 that is true of the torrent thread too, and it was not before.**
-  A worker thread loads its own instance of every module, so the logger's file
-  handle — set once, on the main thread — was null in the worker for the life of
-  the process. Measured over a whole 49 938-line file: zero lines from the piece
-  reader (`read "…"`, `supply "…"`, every wait and its cause) and zero from the
-  torrent pool, against 52 and 36 of them in `docker logs`, which every release
-  destroys. The worker now sends its lines to the main thread, which is the only
-  writer; a line from there reads `torrent-worker: …`.
-- Via container:
-  ```bash
-  ssh ha "sudo docker logs app_b34a1737_torrent_tv_proxy --tail 200"
-  ssh ha "sudo docker exec app_b34a1737_torrent_tv_proxy cat /data/proxy.log | tail -n 300"
-  ```
-- Filter by session: every transcode session logs its id, e.g. `003ed2fd-7c9b-4cd5-9d05-ff875ff2be23`, `hold segment-00068.mp4 failed`, `encode-run failed`, `EXITED_*`.
-- Host file `/data/proxy.log` survives `docker logs` rotation; `core dumps: 1 present` line shows kept dump under `/data`.
-
-SSH to HA requires `MACs hmac-sha2-256-etm@openssh.com,hmac-sha2-512-etm@openssh.com,umac-128-etm@openssh.com` — server `OpenSSH_10.3` on `homeassistant.local` offers only `*-etm` (`Unable to negotiate` / `Corrupted MAC` otherwise). Already in `~/.ssh/config` `Host ha`.
-
-## DO server (webauth.courses, `infra-server-1`)
-
-- Server is `infra-server-1` (`ghcr.io/torrent-tv/server:latest`) on `do` (`206.189.97.152`).
-- Frontend logs are forwarded: browser batches `{sessionId, tag, signalSessionId, lines: [{level,ts,msg}]}` and `POST`s to `https://webauth.courses/api/client-logs` (`server/routes/api/client-logs/post.js:56`), server does `console.log` with prefix `[client <tag> <id> sig=<webrtcSessionId>]`. They appear together with backend logs in the same container.
-- Via container:
-  ```bash
-  ssh do "docker logs infra-server-1 --tail 200 | cat"
-  # filter a single viewing:
-  ssh do "docker logs infra-server-1 --tail 500 | grep 003ed2fd"
-  ssh do "docker logs infra-server-1 --tail 500 | grep '\[client'"
-  ```
-- No need to open eruda or copy browser console on phone — it is already in `infra-server-1` logs.
-
-## Quick triage
-
-- Rewind/seek bug (hold 0ms → 500): HA `hold ... failed after 0ms → 500` + `encode-run` lines for the same `<sessionId>`, and DO `[client ...] fragLoadError / levelLoadError 500` for same `sn`.
-- Cushion / link budget: HA `memory: rss=... anon=...` and `cushion` lines; DO `[eta]` / `[cushion]` from client.
-- Update check: `ssh ha "sudo docker exec hassio_cli ha apps info b34a1737_torrent_tv_proxy | grep version"` and `ssh ha "sudo docker ps --filter name=app_b34a1737_torrent_tv_proxy"`.
-
-## Related
-
-- `ha-addon/CLAUDE.md` — addon build/update detour via `hassio_cli`, cache-bust via `config.yaml` version.
-- `docs/container-architecture.md` — what container/track classes log and where.
-- `server/routes/api/client-logs/post.js:1` — sanitization (control chars → space, `MAX_LINES 50`, `MAX_MSG_LEN 2000`).
+# Logs — where to look
+
+No browser console copy-paste is needed: the page forwards its own log. But it
+lands in TWO places depending on the phase of the session, and `docker logs` is
+only one of them — see "Browser logs are in TWO places" below before concluding
+anything from a half-session.
+
+## HA proxy (aarch64, addon `b34a1737_torrent_tv_proxy`)
+
+Image `b34a1737/aarch64-addon-torrent_tv_proxy:<version>` = `@torrent-tv/proxy` `<version>` (see `ha-addon/torrent_tv_proxy/config.yaml`).
+
+- Console + file are the same: the proxy logs to both `stdout` and `/data/proxy.log` on start (`logging to /data/proxy.log as well as the console`).
+- **Since 2.71.0 that is true of the torrent thread too, and it was not before.**
+  A worker thread loads its own instance of every module, so the logger's file
+  handle — set once, on the main thread — was null in the worker for the life of
+  the process. Measured over a whole 49 938-line file: zero lines from the piece
+  reader (`read "…"`, `supply "…"`, every wait and its cause) and zero from the
+  torrent pool, against 52 and 36 of them in `docker logs`, which every release
+  destroys. The worker now sends its lines to the main thread, which is the only
+  writer; a line from there reads `torrent-worker: …`.
+- Via container:
+  ```bash
+  ssh ha "sudo docker logs app_b34a1737_torrent_tv_proxy --tail 200"
+  ssh ha "sudo docker exec app_b34a1737_torrent_tv_proxy cat /data/proxy.log | tail -n 300"
+  ```
+- Filter by session: every transcode session logs its id, e.g. `003ed2fd-7c9b-4cd5-9d05-ff875ff2be23`, `hold segment-00068.mp4 failed`, `encode-run failed`, `EXITED_*`.
+- Host file `/data/proxy.log` survives `docker logs` rotation; `core dumps: 1 present` line shows kept dump under `/data`.
+
+SSH to HA requires `MACs hmac-sha2-256-etm@openssh.com,hmac-sha2-512-etm@openssh.com,umac-128-etm@openssh.com` — server `OpenSSH_10.3` on `homeassistant.local` offers only `*-etm` (`Unable to negotiate` / `Corrupted MAC` otherwise). Already in `~/.ssh/config` `Host ha`.
+
+## DO server (webauth.courses, `infra-server-1`)
+
+- Server is `infra-server-1` (`ghcr.io/torrent-tv/server:latest`) on `do` (`206.189.97.152`).
+- Frontend logs reach here only in the phases the proxy cannot be reached in — see "Browser logs are in TWO places" below. When they do, the server `console.log`s them with the prefix `[client <tag> <id> sig=<webrtcSessionId>]` (`server/routes/api/client-logs/post.js`), in the same container as its own lines.
+- Via container:
+  ```bash
+  ssh do "docker logs infra-server-1 --tail 200 | cat"
+  # filter a single viewing:
+  ssh do "docker logs infra-server-1 --tail 500 | grep 003ed2fd"
+  ssh do "docker logs infra-server-1 --tail 500 | grep '\[client'"
+  ```
+- No need to open eruda or copy the browser console on a phone — it is forwarded.
+
+## Browser logs are in TWO places, split by phase — read both
+
+Until 2026-09-13 the page's whole log went to the droplet's standard output,
+which every release of the server destroys. A viewer reported a desync and a
+frozen picture that day and the analysis ran on half the evidence, so the log
+moved to the proxy — beside the proxy's own, on the same durable directory.
+
+The split is by PHASE, and neither half is the whole session:
+
+1. **Before a transport exists** — the page opening, the proxy being chosen, a
+   connection failing — there is nowhere else to send it, so it goes to the
+   SERVER (`infra-server-1`);
+2. **From the moment the data channel is up**, the page's logger is given a
+   proxy sink (`loading.js`, `setProxySink`) and every batch goes to the PROXY
+   over that channel. This is the bulk of a viewing;
+3. **At unload** it goes to the server again: `navigator.sendBeacon` is the only
+   thing a page that is going away can use, and a data channel is not;
+4. **A batch that cannot reach the proxy** falls back to the server.
+
+So a session that failed while connecting is on the droplet, a session that
+failed while playing is on the addon host, and a complete reading of a long
+failure needs both.
+
+### The files on the proxy
+
+One file per viewing session, in the proxy log's own directory (`/data` on the
+addon host), named so the two halves join without guessing:
+
+```
+client-<YYYYMMDD-HHMMSS UTC of the session start>-<sessionId:8>-<torrent name:60>-<infoHash:8>.log
+```
+
+A session that has not chosen a torrent yet writes `no-torrent-yet` in that
+last part — the file is keyed by the session id, not by the name, so choosing a
+torrent later does NOT start a second file. Rotated at 16 MB to `<name>.log.1`.
+
+```bash
+ssh ha "sudo docker exec app_b34a1737_torrent_tv_proxy sh -c 'ls -la /data/client-*.log'"
+ssh ha "sudo docker exec app_b34a1737_torrent_tv_proxy sh -c 'cat /data/client-20260913-*.log'"
+```
+
+Implementation: `utils/client-log-file.js`, route `routes/api/client-logs/post.js`.
+
+## Quick triage
+
+- Rewind/seek bug (hold 0ms → 500): HA `hold ... failed after 0ms → 500` + `encode-run` lines for the same `<sessionId>`, and DO `[client ...] fragLoadError / levelLoadError 500` for same `sn`.
+- Cushion / link budget: HA `memory: rss=... anon=...` and `cushion` lines; DO `[eta]` / `[cushion]` from client.
+- Update check: `ssh ha "sudo docker exec hassio_cli ha apps info b34a1737_torrent_tv_proxy | grep version"` and `ssh ha "sudo docker ps --filter name=app_b34a1737_torrent_tv_proxy"`.
+
+## Related
+
+- `ha-addon/CLAUDE.md` — addon build/update detour via `hassio_cli`, cache-bust via `config.yaml` version.
+- `docs/container-architecture.md` — what container/track classes log and where.
+- `routes/api/client-logs/post.js` and `server/routes/api/client-logs/post.js` — the two receivers; both sanitize the same way (control chars → space, `MAX_LINES`, `MAX_MSG_LEN`).

package/package.json

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

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

@@ -1,137 +1,139 @@
-/**
- * Create or return an existing HLS transcode session for a torrent file.
- *
- * POST /api/transcode-sessions
- *
- * @param {import("fastify").FastifyRequest} req
- * @param {import("fastify").FastifyReply} reply
- * @param {{ hlsSessionManager: import("../../../services/hls-session-manager.js").HlsSessionManager, sourceRegistry: object, torrentPool: object }} deps
- * @returns {Promise<void>}
- */
-
-import { logger } from "../../../utils/logger.js";
-
-/**
- * Extract a plain object from the request body, guarding against
- * non-object payloads (arrays, primitives, null).
- *
- * @param {unknown} body
- * @returns {Record<string, unknown>}
- */
-function getPayload(body) {
-  if (body && typeof body === "object" && !Array.isArray(body)) {
-    return body;
-  }
-  return {};
-}
-
-
-export async function handleApiTranscodeSessionsPost(req, reply, { hlsSessionManager, sourceRegistry, torrentPool }) {
-  const payload = getPayload(req.body);
-  const sourceKey = typeof payload.sourceKey === "string" ? payload.sourceKey.trim() : "";
-  const fileIndex = Number(payload.fileIndex);
-  const transcodeVideo = payload.transcodeVideo === true;
-  const transcodeAudio = payload.transcodeAudio === true;
-  const consumerId = typeof payload.consumerId === "string" ? payload.consumerId.trim() : "";
-  const fileName = typeof payload.fileName === "string" ? payload.fileName.trim() : "";
-  const targetWidth = Number(payload.targetWidth);
-  const targetHeight = Number(payload.targetHeight);
-  // Manual quality: the target box is a user-forced resolution, encoded exactly
-  // (capped to source), with the realtime budget's auto-downscale + runtime
-  // downswitch disabled for the session.
-  const manualQuality = payload.manualQuality === true;
-  // Whether this browser will take its audio from a separate rendition group in
-  // the master playlist rather than muxed into the picture. It has to say so:
-  // publishing renditions AND muxing the same audio would play it twice, while
-  // a browser that does not know about them would get no sound at all.
-  const audioRenditions = payload.audioRenditions === true;
-  const startPositionSeconds = Number(payload.startPositionSeconds);
-  const audioTrackIndex = Number(payload.audioTrackIndex);
-  // Which container to produce. The browser knows what its media stack will
-  // accept for the tracks it asked to be copied; an absent or unknown value
-  // leaves the proxy's own `--segment-format` in charge.
-  const segmentFormatId =
-    typeof payload.segmentFormat === "string" ? payload.segmentFormat.trim() : "";
-
-  if (!sourceKey || !Number.isInteger(fileIndex) || fileIndex < 0) {
-    return reply.code(400).send({ error: "sourceKey and valid fileIndex are required." });
-  }
-
-  try {
-    const session = await hlsSessionManager.createOrGetSession({
-      sourceKey,
-      fileIndex,
-      transcodeVideo,
-      transcodeAudio,
-      consumerId,
-      fileName,
-      targetWidth: Number.isInteger(targetWidth) && targetWidth > 0 ? targetWidth : 0,
-      targetHeight: Number.isInteger(targetHeight) && targetHeight > 0 ? targetHeight : 0,
-      manualQuality,
-      audioRenditions,
-      startPositionSeconds:
-        Number.isFinite(startPositionSeconds) && startPositionSeconds > 0
-          ? startPositionSeconds
-          : 0,
-      audioTrackIndex:
-        Number.isInteger(audioTrackIndex) && audioTrackIndex > 0 ? audioTrackIndex : 0,
-      segmentFormatId
-    });
-    // The index of quality variants, when this session has more than one to
-    // offer. Its presence is what tells the browser it can change quality
-    // without a new session: the player switches variants itself, appending the
-    // new one after what is already buffered. Absent for a copied video, whose
-    // segments are cut at the source's own keyframes and so cannot be spliced
-    // with a re-encoded rung.
-    const hasVariants = hlsSessionManager.buildMasterPlaylist(session.id) !== null;
-    return reply.send({
-      sessionId: session.id,
-      playlistPath: `/transcode/${session.id}/index.m3u8`,
-      ...(hasVariants
-        ? {
-            masterPath: `/transcode/${session.id}/master.m3u8`,
-            // Which of the master's variants this session IS. The browser pins
-            // the player to it, so loading the master costs nothing: an encoder
-            // is already producing that height, and any other rung would be a
-            // second cold start before the first frame.
-            variantHeight: hlsSessionManager.liveOutputs.variantHeightOf(session)
-          }
-        : {}),
-      // The heights this host will actually serve this file at, largest first
-      // — the ladder minus every rung it cannot produce faster than it is
-      // watched. The browser needs it whether or not a master exists: without
-      // it, it fell back to a ladder of its own invention and offered rungs the
-      // proxy had just refused, and picking one re-opened the session at a
-      // height measured at a third of realtime.
-      offeredHeights: hlsSessionManager.offeredHeights(session),
-      // What this session's output will carry, stated rather than left to be
-      // discovered. The browser checks what it actually got against this: a
-      // track that never arrives is otherwise noticed only by its absence,
-      // minutes later, as a black picture with working sound.
-      tracks: hlsSessionManager.declaredTracks(session),
-      // How far ahead of the viewer this proxy lets the encoder run, in seconds
-      // of playback. The browser sizes its own forward buffer from it, so the
-      // two sides agree by construction instead of each carrying a constant of
-      // its own — which is how the browser came to hold thirty seconds while
-      // two minutes stood produced on disk (roadmap item 4).
-      lookaheadSeconds: hlsSessionManager.lookaheadSeconds
-    });
-  } catch (error) {
-    if (error instanceof Error && error.code === "TRANSCODE_DISABLED") {
-      return reply.code(409).send({ error: error.message });
-    }
-    const message = error instanceof Error ? error.message : String(error);
-    // Say why on the proxy's own log, not only in the answer. This route
-    // answered 500 for every viewer of proxy 2.9.101-2.9.102 (an undeclared
-    // constant) and the addon log carried nothing but the data-channel layer's
-    // bare "→ 500": the cause had to be recovered by replaying the request
-    // against the live proxy. The stack is worth the two lines it costs — a
-    // programming error here is invisible to the viewer, who only sees that
-    // nothing plays.
-    logger.error(
-      `transcode-sessions: ${sourceKey}:${fileIndex} failed to prepare: ${message}\n` +
-        `${error instanceof Error ? (error.stack ?? "") : ""}`
-    );
-    return reply.code(500).send({ error: `Failed to prepare transcode session: ${message}` });
-  }
-}
+/**
+ * Create or return an existing HLS transcode session for a torrent file.
+ *
+ * POST /api/transcode-sessions
+ *
+ * @param {import("fastify").FastifyRequest} req
+ * @param {import("fastify").FastifyReply} reply
+ * @param {{ hlsSessionManager: import("../../../services/hls-session-manager.js").HlsSessionManager, sourceRegistry: object, torrentPool: object }} deps
+ * @returns {Promise<void>}
+ */
+
+import { logger } from "../../../utils/logger.js";
+
+/**
+ * Extract a plain object from the request body, guarding against
+ * non-object payloads (arrays, primitives, null).
+ *
+ * @param {unknown} body
+ * @returns {Record<string, unknown>}
+ */
+function getPayload(body) {
+  if (body && typeof body === "object" && !Array.isArray(body)) {
+    return body;
+  }
+  return {};
+}
+
+
+export async function handleApiTranscodeSessionsPost(req, reply, { hlsSessionManager, sourceRegistry, torrentPool }) {
+  const payload = getPayload(req.body);
+  const sourceKey = typeof payload.sourceKey === "string" ? payload.sourceKey.trim() : "";
+  const fileIndex = Number(payload.fileIndex);
+  const transcodeVideo = payload.transcodeVideo === true;
+  const transcodeAudio = payload.transcodeAudio === true;
+  const consumerId = typeof payload.consumerId === "string" ? payload.consumerId.trim() : "";
+  const fileName = typeof payload.fileName === "string" ? payload.fileName.trim() : "";
+  const targetWidth = Number(payload.targetWidth);
+  const targetHeight = Number(payload.targetHeight);
+  // The target box is produced exactly (capped to source), with the realtime
+  // budget's auto-downscale and runtime downswitch off for this session.
+  //
+  // It says nothing about WHO asked — a rung sets it whether the viewer picked
+  // that rung or the player moved itself onto one.
+  const exactSize = payload.exactSize === true;
+  // Whether this browser will take its audio from a separate rendition group in
+  // the master playlist rather than muxed into the picture. It has to say so:
+  // publishing renditions AND muxing the same audio would play it twice, while
+  // a browser that does not know about them would get no sound at all.
+  const audioRenditions = payload.audioRenditions === true;
+  const startPositionSeconds = Number(payload.startPositionSeconds);
+  const audioTrackIndex = Number(payload.audioTrackIndex);
+  // Which container to produce. The browser knows what its media stack will
+  // accept for the tracks it asked to be copied; an absent or unknown value
+  // leaves the proxy's own `--segment-format` in charge.
+  const segmentFormatId =
+    typeof payload.segmentFormat === "string" ? payload.segmentFormat.trim() : "";
+
+  if (!sourceKey || !Number.isInteger(fileIndex) || fileIndex < 0) {
+    return reply.code(400).send({ error: "sourceKey and valid fileIndex are required." });
+  }
+
+  try {
+    const session = await hlsSessionManager.createOrGetSession({
+      sourceKey,
+      fileIndex,
+      transcodeVideo,
+      transcodeAudio,
+      consumerId,
+      fileName,
+      targetWidth: Number.isInteger(targetWidth) && targetWidth > 0 ? targetWidth : 0,
+      targetHeight: Number.isInteger(targetHeight) && targetHeight > 0 ? targetHeight : 0,
+      exactSize,
+      audioRenditions,
+      startPositionSeconds:
+        Number.isFinite(startPositionSeconds) && startPositionSeconds > 0
+          ? startPositionSeconds
+          : 0,
+      audioTrackIndex:
+        Number.isInteger(audioTrackIndex) && audioTrackIndex > 0 ? audioTrackIndex : 0,
+      segmentFormatId
+    });
+    // The index of quality variants, when this session has more than one to
+    // offer. Its presence is what tells the browser it can change quality
+    // without a new session: the player switches variants itself, appending the
+    // new one after what is already buffered. Absent for a copied video, whose
+    // segments are cut at the source's own keyframes and so cannot be spliced
+    // with a re-encoded rung.
+    const hasVariants = hlsSessionManager.buildMasterPlaylist(session.id) !== null;
+    return reply.send({
+      sessionId: session.id,
+      playlistPath: `/transcode/${session.id}/index.m3u8`,
+      ...(hasVariants
+        ? {
+            masterPath: `/transcode/${session.id}/master.m3u8`,
+            // Which of the master's variants this session IS. The browser pins
+            // the player to it, so loading the master costs nothing: an encoder
+            // is already producing that height, and any other rung would be a
+            // second cold start before the first frame.
+            variantHeight: hlsSessionManager.liveOutputs.variantHeightOf(session)
+          }
+        : {}),
+      // The heights this host will actually serve this file at, largest first
+      // — the ladder minus every rung it cannot produce faster than it is
+      // watched. The browser needs it whether or not a master exists: without
+      // it, it fell back to a ladder of its own invention and offered rungs the
+      // proxy had just refused, and picking one re-opened the session at a
+      // height measured at a third of realtime.
+      offeredHeights: hlsSessionManager.offeredHeights(session),
+      // What this session's output will carry, stated rather than left to be
+      // discovered. The browser checks what it actually got against this: a
+      // track that never arrives is otherwise noticed only by its absence,
+      // minutes later, as a black picture with working sound.
+      tracks: hlsSessionManager.declaredTracks(session),
+      // How far ahead of the viewer this proxy lets the encoder run, in seconds
+      // of playback. The browser sizes its own forward buffer from it, so the
+      // two sides agree by construction instead of each carrying a constant of
+      // its own — which is how the browser came to hold thirty seconds while
+      // two minutes stood produced on disk (roadmap item 4).
+      lookaheadSeconds: hlsSessionManager.lookaheadSeconds
+    });
+  } catch (error) {
+    if (error instanceof Error && error.code === "TRANSCODE_DISABLED") {
+      return reply.code(409).send({ error: error.message });
+    }
+    const message = error instanceof Error ? error.message : String(error);
+    // Say why on the proxy's own log, not only in the answer. This route
+    // answered 500 for every viewer of proxy 2.9.101-2.9.102 (an undeclared
+    // constant) and the addon log carried nothing but the data-channel layer's
+    // bare "→ 500": the cause had to be recovered by replaying the request
+    // against the live proxy. The stack is worth the two lines it costs — a
+    // programming error here is invisible to the viewer, who only sees that
+    // nothing plays.
+    logger.error(
+      `transcode-sessions: ${sourceKey}:${fileIndex} failed to prepare: ${message}\n` +
+        `${error instanceof Error ? (error.stack ?? "") : ""}`
+    );
+    return reply.code(500).send({ error: `Failed to prepare transcode session: ${message}` });
+  }
+}

package/services/data-channel-handler.js

@@ -362,6 +362,13 @@ function makeSendQueueWatcher({ log, getTransportSnapshot, witness, usrsctpState
         const snapshot = getTransportSnapshot?.(sessionId) ?? null;
         connection.unknown = snapshot ? 0 : connection.unknown + 1;
         if (connection.unknown >= TRANSPORT_UNKNOWN_HEARTBEATS) {
+          // THE SECOND DETECTOR, and it is the one that has to work: `onClosed`
+          // does not always come — a peer connection can die without it — and
+          // presence is the connection and nothing else, so nothing else will
+          // ever say these people have gone. Until now this ended the watch and
+          // left them registered for the life of the process, holding the
+          // outputs they were watching.
+          connectionGone(sessionId, "the transport stopped answering");
           stop();
           return;
         }