@torrent-tv/proxy 2.87.9 → 2.87.11

package/openspec/changes/chunked-request-bodies/design.md

@@ -1,81 +1,81 @@
-# Design: Chunked request bodies (proxy side)
-
-Written to be executed as specified — the wire format, constants, limits
-and do-NOT list are normative. Read before coding:
-
-- `services/transport/data-channel-handler.js`: the whole file — the wire-protocol
-  doc comment (~lines 9–37), `handleChannel` (onMessage string handling),
-  `handleRequest`, `sendChunk` (the response frame writer whose layout the
-  request frames mirror), `send`.
-
-## Wire protocol (additions)
-
-Existing messages are UNCHANGED. New:
-
-    Browser → Proxy, announcing a chunked request:
-      { type: "request-start", requestId, method, path, query, headers,
-        bodyBytes }          // bodyBytes = exact total body size in bytes
-
-    Browser → Proxy, body frames (BINARY messages — today the proxy only
-    ever receives strings, so binary is unambiguous):
-      byte 0        flags     bit 0: done (last frame)
-                              bit 1: aborted (drop this request, no reply)
-      byte 1        idLen     requestId length in bytes
-      bytes 2..2+N  requestId (ASCII)
-      bytes 2+N..   payload   raw body bytes (UTF-8 of the body string;
-                              may be empty on a done/abort frame)
-
-Identical layout to the response frames (`sendChunk`) — one mental model,
-and the browser already has a parser for it (its builder mirrors it).
-
-No capability negotiation: POC, single-proxy pool, lockstep releases
-(proxy first, then server). The 16 MB `maxMessageSize` advertisement in
-webrtc-manager.js (pending 2.9.35) stays as a one-line transition cover
-for tabs still running the single-send bundle.
-
-## Constants
-
-    PROXY_MAX_REQUEST_BODY_BYTES = 32 * 1024 * 1024
-    PARTIAL_REQUEST_TTL_MS = 60_000
-
-## Assembly (all state per channel, inside `handleChannel`'s closure)
-
-    const partials = new Map(); // requestId → { meta, chunks: [], receivedBytes, timer }
-
-- `request-start`: validate like a legacy request (same path allowlist —
-  run the SAME validation before accepting the body; reject with
-  `response-error` immediately on a bad path). Reject `bodyBytes` >
-  PROXY_MAX_REQUEST_BODY_BYTES with `response-error` "Request body too
-  large." and do NOT create state. Otherwise store `{ meta, chunks: [],
-  receivedBytes: 0 }` and arm the TTL timer.
-- Binary frame: parse header; unknown requestId → ignore (stale/aborted).
-  bit 1 (aborted) → clear timer, delete entry, no reply. Append payload,
-  add to receivedBytes; receivedBytes > bodyBytes (or > the cap) →
-  `response-error` + drop. bit 0 (done): concat chunks → body string via
-  `Buffer.concat(...).toString("utf8")`; receivedBytes !== bodyBytes →
-  `response-error` "Request body size mismatch." and drop; else clear
-  timer, delete entry, and execute through the SAME code path a legacy
-  `request` message takes (factor `handleRequest` so both entry points
-  call one function with `{requestId, method, path, query, headers, body}`).
-- TTL fire: delete entry, log
-  `[dc] Session …: dropped stale partial request <id8> (<receivedBytes>B)`.
-- `channel.onClosed`: clear ALL timers and the map (extend the existing
-  handler — do not replace its logging).
-
-## Logging
-
-Chunked request execution logs the SAME `[dc] <method> <path>` line as
-legacy, with `body=<bytes> bytes (chunked)`.
-
-## Rules — do NOT
-
-- Do NOT change the legacy `{type:"request"}` handling, the response
-  framing, ping/pong, or the path allowlist semantics.
-- Do NOT add capability/version negotiation — POC decision, revisit only
-  when the pool has independently-updated proxies.
-- Do NOT revert the 16 MB `maxMessageSize` advertisement (pending 2.9.35).
-- Do NOT hold partial bodies beyond the TTL or channel lifetime; no global
-  (cross-channel) state.
-- Do NOT create a new proxy version: fold into the pending 2.9.35
-  CHANGELOG entry (accumulate bullets, per the versioning rules) and the
-  pending addon 0.2.56 entry.
+# Design: Chunked request bodies (proxy side)
+
+Written to be executed as specified — the wire format, constants, limits
+and do-NOT list are normative. Read before coding:
+
+- `services/transport/data-channel-handler.js`: the whole file — the wire-protocol
+  doc comment (~lines 9–37), `handleChannel` (onMessage string handling),
+  `handleRequest`, `sendChunk` (the response frame writer whose layout the
+  request frames mirror), `send`.
+
+## Wire protocol (additions)
+
+Existing messages are UNCHANGED. New:
+
+    Browser → Proxy, announcing a chunked request:
+      { type: "request-start", requestId, method, path, query, headers,
+        bodyBytes }          // bodyBytes = exact total body size in bytes
+
+    Browser → Proxy, body frames (BINARY messages — today the proxy only
+    ever receives strings, so binary is unambiguous):
+      byte 0        flags     bit 0: done (last frame)
+                              bit 1: aborted (drop this request, no reply)
+      byte 1        idLen     requestId length in bytes
+      bytes 2..2+N  requestId (ASCII)
+      bytes 2+N..   payload   raw body bytes (UTF-8 of the body string;
+                              may be empty on a done/abort frame)
+
+Identical layout to the response frames (`sendChunk`) — one mental model,
+and the browser already has a parser for it (its builder mirrors it).
+
+No capability negotiation: POC, single-proxy pool, lockstep releases
+(proxy first, then server). The 16 MB `maxMessageSize` advertisement in
+webrtc-manager.js (pending 2.9.35) stays as a one-line transition cover
+for tabs still running the single-send bundle.
+
+## Constants
+
+    PROXY_MAX_REQUEST_BODY_BYTES = 32 * 1024 * 1024
+    PARTIAL_REQUEST_TTL_MS = 60_000
+
+## Assembly (all state per channel, inside `handleChannel`'s closure)
+
+    const partials = new Map(); // requestId → { meta, chunks: [], receivedBytes, timer }
+
+- `request-start`: validate like a legacy request (same path allowlist —
+  run the SAME validation before accepting the body; reject with
+  `response-error` immediately on a bad path). Reject `bodyBytes` >
+  PROXY_MAX_REQUEST_BODY_BYTES with `response-error` "Request body too
+  large." and do NOT create state. Otherwise store `{ meta, chunks: [],
+  receivedBytes: 0 }` and arm the TTL timer.
+- Binary frame: parse header; unknown requestId → ignore (stale/aborted).
+  bit 1 (aborted) → clear timer, delete entry, no reply. Append payload,
+  add to receivedBytes; receivedBytes > bodyBytes (or > the cap) →
+  `response-error` + drop. bit 0 (done): concat chunks → body string via
+  `Buffer.concat(...).toString("utf8")`; receivedBytes !== bodyBytes →
+  `response-error` "Request body size mismatch." and drop; else clear
+  timer, delete entry, and execute through the SAME code path a legacy
+  `request` message takes (factor `handleRequest` so both entry points
+  call one function with `{requestId, method, path, query, headers, body}`).
+- TTL fire: delete entry, log
+  `[dc] Session …: dropped stale partial request <id8> (<receivedBytes>B)`.
+- `channel.onClosed`: clear ALL timers and the map (extend the existing
+  handler — do not replace its logging).
+
+## Logging
+
+Chunked request execution logs the SAME `[dc] <method> <path>` line as
+legacy, with `body=<bytes> bytes (chunked)`.
+
+## Rules — do NOT
+
+- Do NOT change the legacy `{type:"request"}` handling, the response
+  framing, ping/pong, or the path allowlist semantics.
+- Do NOT add capability/version negotiation — POC decision, revisit only
+  when the pool has independently-updated proxies.
+- Do NOT revert the 16 MB `maxMessageSize` advertisement (pending 2.9.35).
+- Do NOT hold partial bodies beyond the TTL or channel lifetime; no global
+  (cross-channel) state.
+- Do NOT create a new proxy version: fold into the pending 2.9.35
+  CHANGELOG entry (accumulate bullets, per the versioning rules) and the
+  pending addon 0.2.56 entry.

package/openspec/changes/chunked-request-bodies/proposal.md

@@ -1,53 +1,53 @@
-# Proposal: Chunked request bodies over the data channel (proxy side)
-
-## Why
-
-The browser sends every request as ONE data-channel message, body included.
-Registering a source carries the base64-encoded `.torrent` as that body — a
-big multi-season pack (Poirot, 13 seasons: 420 KB `.torrent` → ~560 KB
-base64) exceeded libdatachannel's default advertised `a=max-message-size`
-of 256 KB, so the browser's `send()` threw "Trying to send message larger
-than max-message-size" and playback dead-ended.
-
-The committed-but-unpublished stopgap (advertise 16 MB, pending 2.9.35)
-lifts the ceiling but keeps the flaw: any single-message body still has a
-hard cap, and a large message is buffered whole on both ends. Responses
-already solved this properly — they stream as small binary frames. Requests
-should be symmetric.
-
-## What Changes
-
-- **Inbound binary body frames.** The proxy accepts request bodies as
-  binary frames with EXACTLY the response-frame layout
-  (`[flags][idLen][requestId][payload]`, bit 0 = done; new bit 1 = aborted),
-  announced by a new `{type:"request-start", …, bodyBytes}` control message.
-  On the done frame the assembled body runs through the SAME request
-  execution path as a legacy request. Bounded: per-body cap 32 MB, partial
-  bodies dropped after a 60 s TTL or an abort frame, all per-channel state
-  freed on channel close.
-- **No capability negotiation.** POC: the pool is one proxy, released in
-  lockstep with the site (proxy first, then server). The browser just uses
-  chunked frames for large bodies; this proxy just understands them.
-- **The 16 MB `max-message-size` advertisement (pending 2.9.35) stays** —
-  a single config value, no logic: it covers the transition window while
-  already-open tabs still run the single-send bundle.
-- **Observability**: the `[dc]` request log line reports chunked bodies
-  (`body=<bytes> bytes (chunked)`).
-
-Browser-side counterpart (chunk writer, threshold, backpressure, abort) is
-the server repo's `chunked-request-bodies` change. Release order: proxy
-(with addon bump) FIRST, then server.
-
-## Capabilities
-
-### New Capabilities
-
-- `chunked-request-bodies`: request-body transport over the data channel.
-
-## Impact
-
-- `services/transport/data-channel-handler.js` — binary inbound frame parsing;
-  per-channel partial-body assembly with caps/TTL; `request-start`
-  handling; shared execution path.
-- Release: folds into the PENDING proxy 2.9.35 (extend its CHANGELOG entry;
-  do not create a new version) + ha-addon 0.2.56 (same rule).
+# Proposal: Chunked request bodies over the data channel (proxy side)
+
+## Why
+
+The browser sends every request as ONE data-channel message, body included.
+Registering a source carries the base64-encoded `.torrent` as that body — a
+big multi-season pack (Poirot, 13 seasons: 420 KB `.torrent` → ~560 KB
+base64) exceeded libdatachannel's default advertised `a=max-message-size`
+of 256 KB, so the browser's `send()` threw "Trying to send message larger
+than max-message-size" and playback dead-ended.
+
+The committed-but-unpublished stopgap (advertise 16 MB, pending 2.9.35)
+lifts the ceiling but keeps the flaw: any single-message body still has a
+hard cap, and a large message is buffered whole on both ends. Responses
+already solved this properly — they stream as small binary frames. Requests
+should be symmetric.
+
+## What Changes
+
+- **Inbound binary body frames.** The proxy accepts request bodies as
+  binary frames with EXACTLY the response-frame layout
+  (`[flags][idLen][requestId][payload]`, bit 0 = done; new bit 1 = aborted),
+  announced by a new `{type:"request-start", …, bodyBytes}` control message.
+  On the done frame the assembled body runs through the SAME request
+  execution path as a legacy request. Bounded: per-body cap 32 MB, partial
+  bodies dropped after a 60 s TTL or an abort frame, all per-channel state
+  freed on channel close.
+- **No capability negotiation.** POC: the pool is one proxy, released in
+  lockstep with the site (proxy first, then server). The browser just uses
+  chunked frames for large bodies; this proxy just understands them.
+- **The 16 MB `max-message-size` advertisement (pending 2.9.35) stays** —
+  a single config value, no logic: it covers the transition window while
+  already-open tabs still run the single-send bundle.
+- **Observability**: the `[dc]` request log line reports chunked bodies
+  (`body=<bytes> bytes (chunked)`).
+
+Browser-side counterpart (chunk writer, threshold, backpressure, abort) is
+the server repo's `chunked-request-bodies` change. Release order: proxy
+(with addon bump) FIRST, then server.
+
+## Capabilities
+
+### New Capabilities
+
+- `chunked-request-bodies`: request-body transport over the data channel.
+
+## Impact
+
+- `services/transport/data-channel-handler.js` — binary inbound frame parsing;
+  per-channel partial-body assembly with caps/TTL; `request-start`
+  handling; shared execution path.
+- Release: folds into the PENDING proxy 2.9.35 (extend its CHANGELOG entry;
+  do not create a new version) + ha-addon 0.2.56 (same rule).

package/openspec/changes/chunked-request-bodies/specs/chunked-request-bodies/spec.md

@@ -1,30 +1,30 @@
-# chunked-request-bodies — delta spec (proxy)
-
-## ADDED Requirements
-
-### Requirement: Request bodies arrive in bounded binary chunks
-
-The proxy SHALL accept a request whose body is delivered as binary frames
-(mirroring the response-frame layout) announced by a `request-start`
-control message, assemble it, and execute it through the same path as a
-single-message request. Assembly SHALL be bounded: a per-body byte cap, a
-TTL for incomplete bodies, an abort flag that drops the partial state, and
-release of all partial state when the channel closes. Legacy single-message
-requests SHALL keep working unchanged.
-
-#### Scenario: Large .torrent registration
-- **WHEN** the browser registers a multi-season torrent whose base64 body
-  exceeds any single-message limit
-- **THEN** the body arrives in frames, the source registers, and the
-  response streams back exactly as for a small request
-
-#### Scenario: Oversized or inconsistent body
-- **WHEN** the announced or delivered size exceeds the cap, or the
-  delivered bytes do not match the announcement
-- **THEN** the proxy replies with a response-error for that request and
-  drops the partial state; the channel and other requests are unaffected
-
-#### Scenario: Sender vanishes mid-body
-- **WHEN** frames stop arriving (tab closed, aborted without a frame)
-- **THEN** the partial body is dropped after the TTL (or immediately on
-  channel close) and its memory is released
+# chunked-request-bodies — delta spec (proxy)
+
+## ADDED Requirements
+
+### Requirement: Request bodies arrive in bounded binary chunks
+
+The proxy SHALL accept a request whose body is delivered as binary frames
+(mirroring the response-frame layout) announced by a `request-start`
+control message, assemble it, and execute it through the same path as a
+single-message request. Assembly SHALL be bounded: a per-body byte cap, a
+TTL for incomplete bodies, an abort flag that drops the partial state, and
+release of all partial state when the channel closes. Legacy single-message
+requests SHALL keep working unchanged.
+
+#### Scenario: Large .torrent registration
+- **WHEN** the browser registers a multi-season torrent whose base64 body
+  exceeds any single-message limit
+- **THEN** the body arrives in frames, the source registers, and the
+  response streams back exactly as for a small request
+
+#### Scenario: Oversized or inconsistent body
+- **WHEN** the announced or delivered size exceeds the cap, or the
+  delivered bytes do not match the announcement
+- **THEN** the proxy replies with a response-error for that request and
+  drops the partial state; the channel and other requests are unaffected
+
+#### Scenario: Sender vanishes mid-body
+- **WHEN** frames stop arriving (tab closed, aborted without a frame)
+- **THEN** the partial body is dropped after the TTL (or immediately on
+  channel close) and its memory is released

package/openspec/changes/chunked-request-bodies/tasks.md

@@ -1,40 +1,40 @@
-# Tasks: Chunked request bodies (proxy side)
-
-Execute in order; design.md is normative. Read the code regions listed at
-its top first.
-
-## 1. Implementation
-
-- [ ] 1.1 `transport/data-channel-handler.js`: factor the execution tail of
-      `handleRequest` so a legacy `request` message and an assembled
-      chunked request run the SAME function. `node --check`.
-- [ ] 1.2 `request-start` + binary inbound frames + per-channel assembly
-      with cap (32 MB), size-mismatch check, abort flag (bit 1), TTL
-      (60 s), cleanup on channel close. Unknown-requestId frames ignored.
-- [ ] 1.3 Logging: `body=<bytes> bytes (chunked)` on execution; stale-drop
-      line on TTL.
-
-## 2. Verification
-
-- [ ] 2.1 Node loopback test (two node-datachannel PeerConnections in one
-      script, like the SDP test): drive a request-start + 64 KB frames of a
-      ~600 KB body through a real channel into a handler instance wired to
-      a stub local server; assert the assembled body bytes match and a
-      response comes back. Also: abort frame → no reply, state dropped;
-      oversized announcement → response-error.
-- [ ] 2.2 Legacy regression: single-message request path byte-identical
-      behaviour (run an existing small request through both entry points).
-- [ ] 2.3 E2E (after the server-side change lands in preview): local stack
-      — preview server + local proxy (`node bin/cli.js --server-url
-      ws://localhost:8080`), register the real Poirot `.torrent`
-      (C:\Users\AntonNemtsev\Downloads\Пуаро_…​.torrent, ~560 KB base64)
-      via the UI; plan returns; `[dc] … body=… (chunked)` in the proxy log.
-
-## 3. Release
-
-- [ ] 3.1 EXTEND the pending 2.9.35 CHANGELOG entry (do not bump again) and
-      the pending addon 0.2.56 entry.
-- [ ] 3.2 `npm run patch` in proxy (publishes 2.9.35), push addon bump,
-      update the addon in HA; verify `Starting @torrent-tv/proxy v2.9.35`
-      in the addon log. Proxy FIRST, then addon, then the server-side
-      change releases independently.
+# Tasks: Chunked request bodies (proxy side)
+
+Execute in order; design.md is normative. Read the code regions listed at
+its top first.
+
+## 1. Implementation
+
+- [ ] 1.1 `transport/data-channel-handler.js`: factor the execution tail of
+      `handleRequest` so a legacy `request` message and an assembled
+      chunked request run the SAME function. `node --check`.
+- [ ] 1.2 `request-start` + binary inbound frames + per-channel assembly
+      with cap (32 MB), size-mismatch check, abort flag (bit 1), TTL
+      (60 s), cleanup on channel close. Unknown-requestId frames ignored.
+- [ ] 1.3 Logging: `body=<bytes> bytes (chunked)` on execution; stale-drop
+      line on TTL.
+
+## 2. Verification
+
+- [ ] 2.1 Node loopback test (two node-datachannel PeerConnections in one
+      script, like the SDP test): drive a request-start + 64 KB frames of a
+      ~600 KB body through a real channel into a handler instance wired to
+      a stub local server; assert the assembled body bytes match and a
+      response comes back. Also: abort frame → no reply, state dropped;
+      oversized announcement → response-error.
+- [ ] 2.2 Legacy regression: single-message request path byte-identical
+      behaviour (run an existing small request through both entry points).
+- [ ] 2.3 E2E (after the server-side change lands in preview): local stack
+      — preview server + local proxy (`node bin/cli.js --server-url
+      ws://localhost:8080`), register the real Poirot `.torrent`
+      (C:\Users\AntonNemtsev\Downloads\Пуаро_…​.torrent, ~560 KB base64)
+      via the UI; plan returns; `[dc] … body=… (chunked)` in the proxy log.
+
+## 3. Release
+
+- [ ] 3.1 EXTEND the pending 2.9.35 CHANGELOG entry (do not bump again) and
+      the pending addon 0.2.56 entry.
+- [ ] 3.2 `npm run patch` in proxy (publishes 2.9.35), push addon bump,
+      update the addon in HA; verify `Starting @torrent-tv/proxy v2.9.35`
+      in the addon log. Proxy FIRST, then addon, then the server-side
+      change releases independently.

package/openspec/changes/cold-start/design.md

@@ -1,98 +1,98 @@
-# Design: Cold-start reduction (proxy side)
-
-Written to be executed as specified. Read before coding:
-
-- `services/playback-planner.js`: `probeStreamCodecs` (how the ffmpeg banner
-  is parsed today), `getPlan` (prefetch → probe → pending loop → plan cache
-  and its key/invalidation).
-- `services/hls-session-manager.js`: `probeInputMediaInfo` (~line 383 — what
-  it parses: durationSeconds, width, height, fps, startTime, isHdr),
-  `createSession` (~line 806: the probe call at ~817, keyframe probe at
-  ~854), the segment-ready path (where segment 00000 first becomes
-  servable — grep the long-poll the `routes/transcode/session-file/get.js`
-  route uses).
-- `services/torrent/torrent-pool.js`: `prefetchFileEdges` (~line 608) — signature
-  `(torrent, fileIndex, { headBytes, tailBytes, timeoutMs })`.
-- `server.js`: how `playbackPlanner` and `hlsSessionManager` are constructed
-  and injected.
-
-## 1. Media-info reuse (kill ffmpeg scan #2)
-
-Both probes run ffmpeg over the same input URL and parse the same stderr
-banner; they just extract different fields. Unify:
-
-1. Extract the banner-parsing helpers that `probeInputMediaInfo` uses
-   (duration/width/height/fps/startTime/HDR detection) so the planner can
-   apply them to ITS probe's stderr. Where they live is the executor's
-   choice (export from hls-session-manager or move to a small shared
-   module) — do NOT duplicate the parsing logic.
-2. In the planner, on a probe whose codecs were detected (the same condition
-   that allows caching the plan), build a `mediaInfo` object
-   `{ durationSeconds, width, height, fps, startTime, isHdr }` and cache it
-   ALONGSIDE the plan — same key, same lifetime, same invalidation. A
-   pending (empty) probe caches nothing, exactly like the plan.
-3. Planner exposes `getCachedMediaInfo({ sourceKey, fileIndex })` →
-   `MediaInfo | null`.
-4. `server.js` passes it into HlsSessionManager (new constructor option
-   `getCachedMediaInfo`).
-5. `createSession`:
-
-       const cached = this.getCachedMediaInfo?.({ sourceKey, fileIndex }) ?? null;
-       const usable = cached
-         && Number.isFinite(cached.durationSeconds) && cached.durationSeconds > 0
-         && Number.isFinite(cached.width) && cached.width > 0
-         && Number.isFinite(cached.height) && cached.height > 0;
-       const mediaInfo = usable ? cached : await probeInputMediaInfo(this.ffmpegBin, inputUrl.toString());
-
-   Duration/width/height gate the cache because downstream logic depends on
-   them (synthetic VOD playlist, resolution ladder); fps/startTime/isHdr
-   have safe defaults and do not gate. The probe stays as the fallback —
-   behaviour is unchanged whenever the cache cannot serve.
-
-Keyframe probe (`probeVideoKeyframeTimes`) is NOT touched: it runs only on
-the video-copy path and probes different data (packet flags, not the
-banner).
-
-## 2. Body-start prefetch
-
-In `getPlan`, at the point where the probe succeeded and the plan is about
-to be cached/returned, fire and FORGET:
-
-    void torrentPool.prefetchFileEdges(torrent, fileIndex, {
-      headBytes: BODY_PREFETCH_BYTES, // 16 MB
-      tailBytes: 0,
-      timeoutMs: 60_000
-    }).catch(() => {});
-
-    const BODY_PREFETCH_BYTES = 16 * 1024 * 1024;
-
-No new torrent-pool method — `prefetchFileEdges` with `tailBytes: 0` is
-exactly a head prefetch. Not awaited: the client's session-create follows
-within a couple of seconds and ffmpeg reads sequentially behind the
-prefetch. 16 MB ≈ 25 s of typical 5 Mbit media — covers the first segments
-without denting the disk cap. Do NOT start it on pending polls (the header
-prefetch must keep absolute priority while the probe is starving).
-
-## 3. Stage timings
-
-- `createSession` measures and logs (one line, existing logger, prefix
-  matches the session log style):
-
-      cold-start <sessionId8>: media-info=<ms> (cached|probed) keyframes=<ms|skipped> create-total=<ms>
-
-- When the FIRST segment file of a fresh session becomes servable (the
-  long-poll in the session-file path returns it), log once per session:
-
-      cold-start <sessionId8>: first-segment ready +<ms since createSession entry>
-
-  Store the create-entry timestamp on the session object; guard with a
-  boolean so the line logs once.
-
-## Rules — do NOT
-
-- Do NOT change probe semantics, the pending/poll contract, or the plan
-  cache key.
-- Do NOT prioritise body bytes before the probe has succeeded.
-- Do NOT make session create fail on a cache problem — any doubt → fall
-  back to the probe.
-- No behavioural change for the video-copy path beyond the timing lines.
+# Design: Cold-start reduction (proxy side)
+
+Written to be executed as specified. Read before coding:
+
+- `services/playback-planner.js`: `probeStreamCodecs` (how the ffmpeg banner
+  is parsed today), `getPlan` (prefetch → probe → pending loop → plan cache
+  and its key/invalidation).
+- `services/hls-session-manager.js`: `probeInputMediaInfo` (~line 383 — what
+  it parses: durationSeconds, width, height, fps, startTime, isHdr),
+  `createSession` (~line 806: the probe call at ~817, keyframe probe at
+  ~854), the segment-ready path (where segment 00000 first becomes
+  servable — grep the long-poll the `routes/transcode/session-file/get.js`
+  route uses).
+- `services/torrent/torrent-pool.js`: `prefetchFileEdges` (~line 608) — signature
+  `(torrent, fileIndex, { headBytes, tailBytes, timeoutMs })`.
+- `server.js`: how `playbackPlanner` and `hlsSessionManager` are constructed
+  and injected.
+
+## 1. Media-info reuse (kill ffmpeg scan #2)
+
+Both probes run ffmpeg over the same input URL and parse the same stderr
+banner; they just extract different fields. Unify:
+
+1. Extract the banner-parsing helpers that `probeInputMediaInfo` uses
+   (duration/width/height/fps/startTime/HDR detection) so the planner can
+   apply them to ITS probe's stderr. Where they live is the executor's
+   choice (export from hls-session-manager or move to a small shared
+   module) — do NOT duplicate the parsing logic.
+2. In the planner, on a probe whose codecs were detected (the same condition
+   that allows caching the plan), build a `mediaInfo` object
+   `{ durationSeconds, width, height, fps, startTime, isHdr }` and cache it
+   ALONGSIDE the plan — same key, same lifetime, same invalidation. A
+   pending (empty) probe caches nothing, exactly like the plan.
+3. Planner exposes `getCachedMediaInfo({ sourceKey, fileIndex })` →
+   `MediaInfo | null`.
+4. `server.js` passes it into HlsSessionManager (new constructor option
+   `getCachedMediaInfo`).
+5. `createSession`:
+
+       const cached = this.getCachedMediaInfo?.({ sourceKey, fileIndex }) ?? null;
+       const usable = cached
+         && Number.isFinite(cached.durationSeconds) && cached.durationSeconds > 0
+         && Number.isFinite(cached.width) && cached.width > 0
+         && Number.isFinite(cached.height) && cached.height > 0;
+       const mediaInfo = usable ? cached : await probeInputMediaInfo(this.ffmpegBin, inputUrl.toString());
+
+   Duration/width/height gate the cache because downstream logic depends on
+   them (synthetic VOD playlist, resolution ladder); fps/startTime/isHdr
+   have safe defaults and do not gate. The probe stays as the fallback —
+   behaviour is unchanged whenever the cache cannot serve.
+
+Keyframe probe (`probeVideoKeyframeTimes`) is NOT touched: it runs only on
+the video-copy path and probes different data (packet flags, not the
+banner).
+
+## 2. Body-start prefetch
+
+In `getPlan`, at the point where the probe succeeded and the plan is about
+to be cached/returned, fire and FORGET:
+
+    void torrentPool.prefetchFileEdges(torrent, fileIndex, {
+      headBytes: BODY_PREFETCH_BYTES, // 16 MB
+      tailBytes: 0,
+      timeoutMs: 60_000
+    }).catch(() => {});
+
+    const BODY_PREFETCH_BYTES = 16 * 1024 * 1024;
+
+No new torrent-pool method — `prefetchFileEdges` with `tailBytes: 0` is
+exactly a head prefetch. Not awaited: the client's session-create follows
+within a couple of seconds and ffmpeg reads sequentially behind the
+prefetch. 16 MB ≈ 25 s of typical 5 Mbit media — covers the first segments
+without denting the disk cap. Do NOT start it on pending polls (the header
+prefetch must keep absolute priority while the probe is starving).
+
+## 3. Stage timings
+
+- `createSession` measures and logs (one line, existing logger, prefix
+  matches the session log style):
+
+      cold-start <sessionId8>: media-info=<ms> (cached|probed) keyframes=<ms|skipped> create-total=<ms>
+
+- When the FIRST segment file of a fresh session becomes servable (the
+  long-poll in the session-file path returns it), log once per session:
+
+      cold-start <sessionId8>: first-segment ready +<ms since createSession entry>
+
+  Store the create-entry timestamp on the session object; guard with a
+  boolean so the line logs once.
+
+## Rules — do NOT
+
+- Do NOT change probe semantics, the pending/poll contract, or the plan
+  cache key.
+- Do NOT prioritise body bytes before the probe has succeeded.
+- Do NOT make session create fail on a cache problem — any doubt → fall
+  back to the probe.
+- No behavioural change for the video-copy path beyond the timing lines.