@torrent-tv/proxy 2.89.17 → 2.89.19

package/openspec/changes/adaptive-bitrate/design.md

@@ -1,92 +0,0 @@
-# Design: Adaptive bitrate (proxy)
-
-Read before coding: `services/encode/hwaccel.js` (`chooseSoftwareEncodeSettings`,
-the software descriptor's `buildVideoArgs`), `services/hls-session-manager.js`
-(the `BUDGET_*` constants, `#chooseEncodeBudget`, the budget interval check
-`#enforceRealtimeBudget`, `#classifyTranscodeBound`, `#applyBudgetDownshift`,
-session fields around `budgetLadder`), `routes/api/transcode-sessions/`
-(route file conventions), `server.js` (route wiring, deps injection).
-
-## (a) Caps — constrained CRF
-
-Nominal H.264 rates by rung height (nearest rung wins for odd heights):
-
-    RUNG_NOMINAL_KBPS = { 1080: 5000, 720: 2800, 480: 1400, 360: 800, 240: 400 }
-    CAP_MAXRATE_FACTOR = 1.3
-    CAP_BUFSIZE_FACTOR = 1.5
-
-In the software descriptor's video args (where `-crf`/`-preset` are emitted),
-add for encode height H (the actual encode height after budget/manual
-selection, not the source height):
-
-    -maxrate <round(nominal(H) * 1.3)>k
-    -bufsize <round(nominal(H) * 1.5)>k
-
-CRF stays the quality driver; the caps only bound peaks (standard
-constrained-CRF). Do NOT touch hardware descriptors in this change.
-
-## (b) Net report intake
-
-Route: `POST /api/transcode-sessions/:id/net-report` (data-channel path, so
-add the prefix to the allowlist regex in `transport/data-channel-handler.js` if not
-covered by the existing `/api/` rule — verify). Body:
-
-    { linkMbps: number, bufferedAheadSec: number }
-
-Validation: both finite numbers, `linkMbps > 0`, else 400. Unknown session →
-404. On success 204. Handler stores on the session:
-
-    session.netReport = { linkMbps, bufferedAheadSec, at: Date.now() }
-
-## (b) Budget-loop trigger
-
-Constants (near the other BUDGET_ constants):
-
-    LINK_REPORT_FRESH_MS = 30_000   // ignore stale reports
-    LINK_SAFETY = 0.8               // usable share of reported link
-    LINK_SLOW_WINDOW_MS = 15_000    // sustained deficit before acting
-    LINK_LOW_BUFFER_SEC = 10        // only act while the viewer runs dry
-
-In the periodic budget check, for each active software-transcode session,
-alongside the CPU check:
-
-    report fresh (now - at < LINK_REPORT_FRESH_MS)?
-    manualQuality not set?
-    observed = observed stream bitrate, Mbit/s — recent produced segment
-               bytes / segment duration (reuse/extend whatever the CPU path
-               reads; a rolling average over the last ~5 segments)
-    deficit = report.linkMbps * LINK_SAFETY < observed
-    if deficit AND report.bufferedAheadSec < LINK_LOW_BUFFER_SEC:
-        accumulate slow-time (same pattern as the CPU slow window)
-        if slow ≥ LINK_SLOW_WINDOW_MS → #applyBudgetDownshift(session,
-            reason "link")   // existing cooldown + step cap + floor apply
-    else: reset the link slow window
-
-`#applyBudgetDownshift` is reused as-is except the log line carries the
-reason: `budget downshift (link) …` vs the current CPU wording, so the
-client-log pipeline can tell them apart in the field.
-
-No upswitch in v1 (mirrors the CPU budget's conservatism). A downshifted
-session stays down until re-opened.
-
-## Interactions
-
-- Caps make `observed` honest: without (a) a complex scene can spike far
-  above nominal and flap the trigger; with caps observed ≤ maxrate.
-- CPU trigger and link trigger share the cooldown inside
-  `#applyBudgetDownshift` — they cannot double-fire.
-- `manualQuality` set → link trigger skipped entirely (user pinned quality
-  explicitly; the proxy respects it, matching the manual-quality contract).
-- Old browsers never POST reports → trigger never fires → behaviour
-  identical to today plus caps.
-
-## Verification
-
-- Unit: nominal table lookup (exact rungs + nearest for odd heights); ffmpeg
-  arg assembly contains the caps; trigger logic with a fake clock (fresh vs
-  stale report, deficit accumulating to a downshift, buffer-high suppresses,
-  manualQuality suppresses).
-- `node --check` on touched files.
-- Field (after the server change ships): cellular session shows
-  `budget downshift (link)` and the stream settles at a rung whose bitrate
-  fits the link; segment sizes bounded (~maxrate × segDur / 8 max).

package/openspec/changes/adaptive-bitrate/proposal.md

@@ -1,56 +0,0 @@
-# Proposal: Adaptive bitrate for thin viewer links (proxy side)
-
-## Why
-
-Field evidence (iPhone on cellular, 2026-07-10, session `14cc1017`): encode
-bitrate is unbounded — transcoded segments reached 9 MB per 4 s (~18 Mbit/s)
-against a measured 1–5.8 Mbit/s cellular link. Result: 45 s prebuffer, buffer
-draining during playback (`bottleneck delta=-7.1s`), "было так себе". The
-realtime budget protects the PROXY's CPU but nothing protects the VIEWER's
-link: quality never adapts to how fast the viewer can actually download.
-
-## What Changes
-
-Two parts, one release:
-
-- **(a) Bitrate caps (constrained CRF).** Software video encodes gain
-  `-maxrate`/`-bufsize` sized per resolution rung from a nominal-rate table
-  (H.264 ladder: 1080p→5000K, 720p→2800K, 480p→1400K, 360p→800K, 240p→400K;
-  nearest rung by encode height). Multipliers from webtor's production
-  ladder: `maxrate = 1.3×` nominal, `bufsize = 1.5×` nominal. CRF/preset
-  selection stays — the caps only bound the peaks that killed the cellular
-  session. Applies to the software (libx264) path; hardware encoders keep
-  their current args (follow-up — their rate-control flags differ and any
-  change must pass the strict startup test on real hardware).
-- **(b) Viewer-link downshift trigger.** A new data-channel route lets the
-  browser report its measured link state (`linkMbps` — rolling median of
-  per-segment transfer throughput; `bufferedAheadSec`) every ~10 s. The
-  existing realtime-budget loop gains a SECOND downshift trigger: when
-  reports are fresh, `manualQuality` is not set, the viewer's link is
-  sustainedly slower than the produced stream (`linkMbps × 0.8 <` observed
-  segment bitrate for ≥ 15 s) AND the viewer's buffer is low (< 10 s), step
-  one rung down via the existing `#applyBudgetDownshift` (same cooldown,
-  step cap, no upswitch v1). Distinct log reason (`reason=link`) so field
-  logs distinguish CPU-bound from link-bound downshifts.
-
-Missing/stale reports change nothing (old clients keep working — the trigger
-simply never fires). Manual quality pins win: when `manualQuality` is set the
-trigger is skipped.
-
-## Capabilities
-
-### Modified Capabilities
-
-- `transcode-quality`: encodes are bitrate-capped per rung; the budget loop
-  adapts to the viewer's link, not only to the proxy's CPU.
-
-## Impact
-
-- `services/encode/hwaccel.js` — nominal-rate table + caps in the software
-  descriptor's video args.
-- `services/hls-session-manager.js` — accept/store net reports per session;
-  link trigger in the budget check; log line.
-- `routes/api/transcode-sessions/net-report/post.js` (new) + `server.js`
-  wiring — report intake.
-- Proxy release + ha-addon bump. The server-side reporter is a separate
-  change (`server/viewer-net-report`); release proxy+addon FIRST.

package/openspec/changes/adaptive-bitrate/specs/adaptive-bitrate/spec.md

@@ -1,51 +0,0 @@
-# adaptive-bitrate — delta spec (proxy)
-
-## ADDED Requirements
-
-### Requirement: Software encodes are bitrate-capped per resolution rung
-
-Software video encodes SHALL carry `-maxrate`/`-bufsize` derived from a
-per-rung nominal-rate table (1.3× / 1.5× of the rung's nominal), keeping the
-existing CRF/preset quality selection (constrained CRF). The cap follows the
-ACTUAL encode height after budget or manual selection.
-
-#### Scenario: Complex scene on a capped encode
-- **WHEN** a transcoded scene would spike far above the rung's nominal rate
-- **THEN** the produced segments stay bounded by the cap instead of reaching
-  multi-megabyte sizes that a thin viewer link cannot download in time
-
-### Requirement: The proxy accepts viewer link reports
-
-A data-channel route SHALL accept periodic reports
-`{ linkMbps, bufferedAheadSec }` for an active transcode session and store
-the latest report with its arrival time. Invalid bodies are rejected;
-unknown sessions get 404; missing reports are not an error condition.
-
-#### Scenario: Old client
-- **WHEN** a browser never sends net reports
-- **THEN** the session behaves exactly as before this change (plus caps)
-
-### Requirement: The budget loop downshifts on a sustained link deficit
-
-When a fresh report shows the viewer's usable link (reported × safety
-margin) sustainedly below the observed produced bitrate AND the viewer's
-buffer is low, the existing budget downshift SHALL step the encode one rung
-down (same cooldown, step cap and floor as the CPU trigger; no upswitch).
-The trigger SHALL be skipped when `manualQuality` is set, when reports are
-stale, or when the viewer's buffer is comfortable. The downshift log line
-SHALL name the reason (`link`) distinctly from the CPU reason.
-
-#### Scenario: Cellular viewer, stream too fat
-- **WHEN** reports show 3 Mbit/s usable link against 6 Mbit/s produced
-  bitrate for longer than the slow window, with a draining buffer
-- **THEN** the encode steps down one rung and the log shows a link-reason
-  downshift
-
-#### Scenario: Slow link but full buffer
-- **WHEN** the link is slower than the stream but the viewer's buffer stays
-  comfortable (e.g. paused playback filling ahead)
-- **THEN** no downshift happens
-
-#### Scenario: Manual quality pinned
-- **WHEN** the viewer picked a forced quality
-- **THEN** link reports never trigger a downshift

package/openspec/changes/adaptive-bitrate/tasks.md

@@ -1,40 +0,0 @@
-# Tasks: Adaptive bitrate (proxy)
-
-## 1. Caps
-
-- [x] 1.1 `encode/hwaccel.js`: `RUNG_NOMINAL_KBPS` table + nearest-rung lookup;
-      software descriptor's video args emit `-maxrate`/`-bufsize`
-      (1.3× / 1.5× nominal for the actual encode height). Hardware
-      descriptors untouched.
-
-## 2. Net report intake
-
-- [x] 2.1 `routes/api/transcode-sessions/net-report/post.js`: validate
-      `{ linkMbps, bufferedAheadSec }`, store
-      `session.netReport = { linkMbps, bufferedAheadSec, at }`, 204/400/404.
-- [x] 2.2 Wire in `server.js`; verify the data-channel path allowlist covers
-      the route.
-
-## 3. Budget trigger
-
-- [x] 3.1 Constants `LINK_REPORT_FRESH_MS`, `LINK_SAFETY`,
-      `LINK_SLOW_WINDOW_MS`, `LINK_LOW_BUFFER_SEC`.
-- [x] 3.2 Observed produced bitrate (rolling, last ~5 segments) available to
-      the budget check.
-- [x] 3.3 Link deficit accumulation + `#applyBudgetDownshift(session,
-      reason "link")`; skip on manualQuality/stale/comfortable buffer; log
-      reason distinctly.
-
-## 4. Verification
-
-- [x] 4.1 Unit: table lookup, arg assembly, trigger logic (fake clock):
-      deficit→downshift, stale report→no-op, high buffer→no-op,
-      manualQuality→no-op.
-- [x] 4.2 `node --check` on touched files.
-
-## 5. Release
-
-- [ ] 5.1 CHANGELOG (next patch) + `npm run patch` (user OTP), then addon
-      bump + push + HA update. Release BEFORE the server reporter change.
-- [ ] 5.2 Field: cellular Poirot/Mavka run shows `budget downshift (link)`
-      and bounded segment sizes; correlate via client-log pipeline.

package/openspec/changes/binary-distribution/.openspec.yaml

@@ -1,2 +0,0 @@
-schema: spec-driven
-created: 2026-07-06

package/openspec/changes/binary-distribution/proposal.md

@@ -1,53 +0,0 @@
-# Proposal: Proxy as a single binary + service registration (research, queued)
-
-## Why
-
-Bare-npm installation assumes Node.js on the host — a real barrier for the
-non-technical proxy owners the pool model targets. Node's Single Executable
-Applications (SEA, stable-ish since Node 20/21) allow shipping the proxy as
-one self-contained binary per platform (win/linux/macOS, x64/arm64): download,
-run, done. A binary can also offer — with the user's explicit consent — to
-register itself as an auto-starting service, closing the "survives reboot"
-gap that the HA addon solves today.
-
-## What Changes (research scope first)
-
-- **SEA build pipeline**: `node --experimental-sea-config` + postject-injected
-  blob, one artifact per platform/arch, published as GitHub release assets
-  alongside the npm package.
-- **Known hard parts to resolve in research**:
-  - Native addons (`node-datachannel`, `utp-native`) cannot live inside the
-    SEA blob — they must ship next to the binary or self-extract on first
-    run to a data dir.
-  - `ffmpeg-static`'s binary likewise ships alongside (or the system ffmpeg
-    is required, as the HA addon already does with `--ffmpeg-bin`).
-- **Service registration (opt-in, explicit user action)**:
-  - Linux: `proxy install-service` writes a systemd unit and runs
-    `systemctl enable --now` (requires sudo — the consent step).
-  - Windows: register via `sc create` / a service wrapper (admin prompt =
-    consent).
-  - macOS: launchd plist in `~/Library/LaunchAgents` (user-level, no admin).
-  - Uninstall counterpart mandatory (`proxy uninstall-service`).
-- Stays deployment-agnostic: the binary is a fourth distribution channel
-  next to HA addon, bare npm and Docker; no code paths may assume it.
-
-## Capabilities
-
-### New Capabilities
-
-- `distribution`: how the proxy is packaged and installed on bare hosts.
-
-### Modified Capabilities
-
-<!-- none -->
-
-## Impact
-
-- Build/release tooling in this repo; a `service` CLI subcommand.
-- No changes to runtime behaviour for existing channels.
-
-## Priority
-
-MINIMAL — explicitly NOT part of the POC (owner decision, 2026-07-07).
-Research for the eventual "pool of non-technical owners" product goal; do
-not pick up while any POC work remains.

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

@@ -1,81 +0,0 @@
-# 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 +0,0 @@
-# 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 +0,0 @@
-# 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 +0,0 @@
-# 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 +0,0 @@
-# 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.

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

@@ -1,62 +0,0 @@
-# Proposal: Cold-start reduction (proxy side)
-
-## Why
-
-Field recordings (mobile tester, 2026-07-08) show ~90 seconds from picking an
-episode to a picture. The proxy owns two chunks of that:
-
-1. **A redundant ffmpeg input scan.** The playback planner probes the input
-   (`probeStreamCodecs`) and CACHES the plan — then `createSession` in
-   hls-session-manager immediately probes the SAME input again
-   (`probeInputMediaInfo`) for duration/resolution/fps/startTime/HDR. Each
-   probe is a full ffmpeg startup + banner scan over the torrent-backed HTTP
-   stream — seconds on the HA host, on the critical path, twice.
-2. **First-segment piece latency.** The planner prefetches only the file
-   EDGES (256 KB head + 2 MB tail — what the codec probe needs). The first
-   segment's encode then needs the first ~10–20 MB of the file BODY, whose
-   pieces start downloading only when ffmpeg asks for them — while the swarm
-   sat mostly idle during the plan poll.
-
-There is also no per-stage timing in the logs, so field regressions in
-session startup are invisible.
-
-## What Changes
-
-- **Reuse the planner's probe in session create.** The planner parses and
-  caches the full media info (duration, width/height, fps, startTime, isHdr)
-  from the probe it already runs; hls-session-manager consults that cache
-  and skips its own `probeInputMediaInfo` on a hit (probe stays as the
-  fallback). One full ffmpeg scan disappears from the critical path.
-- **Prefetch the file-body start once the plan is ready.** After a successful
-  probe, fire-and-forget prefetch of the first 16 MB of the file, so the
-  session's ffmpeg reads hit already-downloaded data instead of paying piece
-  latency at encode time.
-- **Stage timings in the log.** Session create logs probe ms (and
-  cache-hit/probed), keyframe-probe ms, and the time from create to the
-  first servable segment — so cold-start is measurable per stage in the
-  field, next to the client-side summary line (server `cold-start` change).
-
-Client-side counterparts (phase instrumentation, earlier prebuffer start)
-live in the server repo's `cold-start` change. The two changes are
-independent — no wire-format coupling, either releases alone.
-
-NOT in this change (candidates for later, kept out deliberately):
-next-episode speculative prefetch (bandwidth cost needs field data first);
-encoder-side first-segment speed-ups (faster warm-up preset would need a
-mid-stream switch — parked with transcode-quality 2.2b).
-
-## Capabilities
-
-### New Capabilities
-
-- `cold-start`: proxy-side session startup latency behaviour.
-
-## Impact
-
-- `services/playback-planner.js` — parse + cache full media info; expose
-  `getCachedMediaInfo`; body-start prefetch after a successful probe.
-- `services/hls-session-manager.js` — consult the cache in `createSession`;
-  stage-timing log lines.
-- `server.js` — wire `getCachedMediaInfo` into the HlsSessionManager deps.
-- Release: proxy `npm run patch` + ha-addon version bump (standard order:
-  proxy first, then addon).