@torrent-tv/proxy 2.89.16 → 2.89.18

package/openspec/changes/cold-start/specs/cold-start/spec.md

@@ -1,47 +0,0 @@
-# cold-start — delta spec (proxy)
-
-## ADDED Requirements
-
-### Requirement: Session create reuses the planner's probe
-
-Creating an HLS transcode session SHALL NOT re-probe an input whose media
-info the playback planner already probed and cached for the same source and
-file. The cached info is used only when its critical fields (duration,
-width, height) are present and valid; otherwise the session SHALL probe as
-before. Cache lifetime and invalidation follow the plan cache exactly.
-
-#### Scenario: Warm plan, immediate session
-- **WHEN** the browser requests a transcode session right after receiving a
-  playback plan for the same file
-- **THEN** the session starts without a second ffmpeg input scan and its
-  playlist/ladder decisions are identical to what the probe would have
-  produced
-
-#### Scenario: Cache cannot serve
-- **WHEN** no cached media info exists (e.g. proxy restarted between plan
-  and session) or a critical field is missing
-- **THEN** the session probes the input itself, exactly as before this
-  change
-
-### Requirement: The file-body start is warm before the encoder needs it
-
-Once a playback plan probe succeeds, the proxy SHALL prefetch the beginning
-of the file body (bounded, ~16 MB) in the background, without delaying the
-plan response and without competing with a still-running header probe.
-
-#### Scenario: First segment does not wait for pieces
-- **WHEN** the viewer confirms playback within the normal flow (seconds
-  after the plan)
-- **THEN** the encoder's initial reads are served from already-downloaded
-  data and the first segment's production is not blocked on piece download
-
-### Requirement: Session startup is measurable per stage
-
-Session creation SHALL log the media-info acquisition time (and whether it
-was cached or probed), the keyframe-probe time when it runs, and — once per
-session — the time from session-create entry to the first servable segment.
-
-#### Scenario: Field regression triage
-- **WHEN** a tester reports a slow start
-- **THEN** the proxy log shows, for that session, where the time went:
-  media info, keyframes, or first-segment production

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

@@ -1,48 +0,0 @@
-# Tasks: Cold-start reduction (proxy side)
-
-Execute in order; design.md is normative. Read the code regions listed at
-the top of design.md first.
-
-## 1. Media-info reuse
-
-- [ ] 1.1 Make the banner-parse helpers of `probeInputMediaInfo` reusable by
-      the planner (export or shared module — no duplication). `node --check`
-      both files.
-- [ ] 1.2 playback-planner: build + cache `mediaInfo` alongside the plan on
-      a codecs-detected probe; expose `getCachedMediaInfo({ sourceKey,
-      fileIndex })`. Pending probes cache nothing.
-- [ ] 1.3 server.js: pass `getCachedMediaInfo` into HlsSessionManager;
-      hls-session-manager: consult it in `createSession` with the
-      critical-fields gate (duration/width/height), probe as fallback.
-- [ ] 1.4 Verify equivalence: for one file, run plan → session with the
-      cache and (by temporarily disabling the wiring) without it — the
-      session log line (duration, segments, ladder/rung) must be identical.
-
-## 2. Body-start prefetch
-
-- [ ] 2.1 playback-planner: fire-and-forget 16 MB head prefetch
-      (`prefetchFileEdges` with `tailBytes: 0`) at the probe-success point;
-      never on pending polls; never awaited.
-- [ ] 2.2 Verify: on a fresh well-seeded magnet, proxy log/order shows the
-      prefetch starting right after the plan while the session that follows
-      produces its first segment without a piece-wait stall (compare
-      first-segment ms with task 3 timings before/after).
-
-## 3. Stage timings
-
-- [ ] 3.1 `createSession`: one `cold-start …: media-info=<ms> (cached|probed)
-      keyframes=<ms|skipped> create-total=<ms>` line.
-- [ ] 3.2 First-segment-ready line (`+<ms>` since create entry), once per
-      session (timestamp on the session object + boolean guard).
-
-## 4. Verification and release
-
-- [ ] 4.1 Regression: normal HLS transcode start, video-copy start (keyframe
-      probe still runs), seek-restart, quality switch — behaviour unchanged;
-      timings visible in the log.
-- [ ] 4.2 Before/after numbers on the dev HA proxy for one cold magnet:
-      media-info ms (probed → cached) and first-segment ms. Record them in
-      this file.
-- [ ] 4.3 CHANGELOG entry (current version + 1 patch); `npm run patch`; bump
-      ha-addon `config.yaml` + its CHANGELOG; push; update the addon in HA
-      (proxy FIRST, then addon — release order per root CLAUDE.md).

package/openspec/changes/disk-cap/.openspec.yaml

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

package/openspec/changes/disk-cap/proposal.md

@@ -1,37 +0,0 @@
-# Proposal: Global disk cap with LRU eviction (Disk hygiene Level 1, final)
-
-## Why
-
-Downloaded torrent data is already removed on a 300 s idle TTL and at
-shutdown, and orphans are swept at startup — but under pressure (several
-large files opened within the TTL window, or a fast fill) the total can
-still grow unbounded and fill a small Home Assistant host's disk
-(SD/eMMC on a Yellow/Pi is often 16–32 GB). A full disk can take down Home
-Assistant itself. This adds the last missing Level 1 piece: a global cap.
-
-## What Changes
-
-- The pool tracks total downloaded bytes and, when it exceeds a cap, evicts
-  whole torrents with NO active reader, least-recently-used first, until
-  back under the cap (checked every 30 s and reused via the existing
-  remove-with-store path). A torrent that is currently playing is never
-  evicted — we cannot delete what is in use.
-- The cap defaults to `min(10 GB, half of free disk)` (measured via
-  `statfs` on the store filesystem), and is overridable with
-  `--max-disk-bytes` (0 disables).
-
-## Capabilities
-
-### New Capabilities
-
-- `disk-cap`: bounded total on-disk footprint via LRU eviction.
-
-### Modified Capabilities
-
-<!-- none -->
-
-## Impact
-
-- `services/torrent/torrent-pool.js` (access tracking, cap enforcement),
-  `bin/cli.js` (`--max-disk-bytes`), `server.js` (option pass-through);
-  ha-addon bump. Part of the proxy transcode/hygiene batch (2.9.29).

package/openspec/changes/disk-cap/specs/disk-cap/spec.md

@@ -1,25 +0,0 @@
-# disk-cap — delta spec
-
-## ADDED Requirements
-
-### Requirement: Total torrent data is bounded by a disk cap
-The pool SHALL keep the total downloaded torrent footprint under a cap. When
-the total exceeds the cap it SHALL evict whole torrents that have no active
-file reader, least-recently-used first, removing each with its on-disk store,
-until back under the cap or no evictable torrent remains. A torrent with an
-active reader SHALL NEVER be evicted. The cap SHALL default to the smaller of
-10 GB and half the free disk, and be overridable (0 disables).
-
-#### Scenario: Idle torrents evicted under pressure
-- **WHEN** the total downloaded data exceeds the cap and some torrents have no
-  active reader
-- **THEN** the least-recently-used idle torrents are removed with their stores
-  until the total is back under the cap
-
-#### Scenario: Active torrent protected
-- **WHEN** the cap is exceeded but the only large torrent is currently playing
-- **THEN** it is not evicted (the cap cannot delete in-use data)
-
-#### Scenario: Cap disabled
-- **WHEN** the cap is set to 0
-- **THEN** no eviction occurs

package/openspec/changes/disk-cap/tasks.md

@@ -1,19 +0,0 @@
-# Tasks: Global disk cap with LRU eviction
-
-## 1. Implementation
-
-- [x] 1.1 Access tracking (`#lastAccess`) updated on getTorrent (incl. the
-      duplicate-infoHash path) and acquireFile
-- [x] 1.2 Cap computed at construction (`min(10GB, half free)` via statfs) or
-      taken from the `maxDiskBytes` option; 0 disables
-- [x] 1.3 Periodic (30 s) `#enforceDiskCap`: evict zero-reader torrents
-      LRU-first via the existing remove-with-store path; clear timer on
-      destroyAll; drop `#lastAccess` on removal
-- [x] 1.4 `--max-disk-bytes` CLI flag → server.js → pool
-- [x] 1.5 Syntax checks + unit-test the eviction ordering/active-skip
-
-## 2. Release
-
-- [ ] 2.1 Ship in the proxy batch (2.9.29) + ha-addon bump
-- [ ] 2.2 Field-check on the host: open several large files, confirm idle
-      ones are evicted and playback is never interrupted

package/openspec/changes/proxy-observability/.openspec.yaml

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

package/openspec/changes/proxy-observability/design.md

@@ -1,38 +0,0 @@
-# Design: Proxy observability
-
-## Context
-
-Diagnosing the 2026-07-06 failures required docker exec into the addon
-container (version) and offered no explanation for zero-peer torrents.
-See proposal for the three gaps.
-
-## Goals / Non-Goals
-
-**Goals:** remote version visibility; explainable zero-peer torrents; clean
-logs.
-
-**Non-Goals:** peer-origin tags in `[stats]` (tracker/DHT/PEX attribution is
-not cheaply available on WebTorrent's public API — dropped from the original
-proposal scope); structured/queryable log output.
-
-## Decisions
-
-1. **Version via createRequire of package.json** (same pattern as the server
-   repo), passed as a route dep — no version literal to forget on release.
-2. **Announce results from `torrent.discovery.tracker` ("update" event)** —
-   internal WebTorrent API, therefore guarded with optional chaining and a
-   fallback log line when absent; a breaking WebTorrent upgrade degrades to
-   "not logged", never to a crash. Torrent-level `warning` events carry
-   tracker rejections/errors and are a public API.
-3. **SSDP fix = setMaxListeners(0) on the one emitter** right after the
-   first successful map() (the UPnP client is created lazily by it).
-   Alternatives rejected: raising EventEmitter.defaultMaxListeners (global,
-   hides real leaks elsewhere); one shared NatAPI for both mappers (couples
-   TCP/UDP lifecycles for no gain).
-
-## Risks / Trade-offs
-
-- [Announce logging depends on WebTorrent internals] → defensive access +
-  explicit fallback line; covered by the spec's best-effort clause.
-- [Announce lines add log volume] → one line per announce interval
-  (minutes), negligible next to the existing [stats] cadence.

package/openspec/changes/proxy-observability/proposal.md

@@ -1,49 +0,0 @@
-# Proposal: Proxy observability (queued for the next proxy release, 2.9.25)
-
-## Why
-
-Three diagnosis gaps surfaced while debugging the 2026-07-06 mobile playback
-failures:
-
-1. `/healthz` and `/health` return only `{"ok":true}` — there is no way to
-   see the running proxy version remotely (the addon shipped a stale proxy
-   for a whole release and nothing detected it). The server already returns
-   `version` in its healthz; the proxy should match.
-2. Tracker announces are silent: a torrent with zero peers gives no clue
-   whether the tracker rejected the announce (e.g. a private tracker's
-   client whitelist), returned an empty peer list, or was unreachable.
-   WebTorrent surfaces these as `warning` events that nothing logs.
-3. `MaxListenersExceededWarning` for `[Ssdp]` floods the log — the two
-   port-mapper instances (TCP + UDP) plus WebTorrent's own nat-api attach
-   listeners to a shared SSDP emitter.
-
-## What Changes
-
-- `/healthz` and `/health` include the proxy `version` (from package.json),
-  keeping the current `ok` semantics.
-- Torrent-level `warning` events (tracker errors and rejections) are logged;
-  each tracker announce result is logged with the peer count returned.
-  Where cheaply available, peer origin (tracker / DHT / PEX) is tagged in
-  the existing `[stats]` line.
-- SSDP listener leak fixed (raise the max-listeners on the shared emitter or
-  share one discovery instance between the two port mappers).
-
-## Capabilities
-
-### New Capabilities
-
-- `observability`: health/version reporting and peer-discovery diagnostics.
-
-### Modified Capabilities
-
-<!-- none yet — openspec/specs is empty in this repo -->
-
-## Impact
-
-- `routes/healthz/get.js`, `routes/health/get.js` (or their handlers) —
-  version field.
-- `services/torrent/torrent-pool.js` — warning/announce logging, stats origin tags.
-- `services/transport/port-mapper.js` — SSDP listener fix.
-- CHANGELOG entry at current package.json version + 1 patch (2.9.25);
-  requires the usual ha-addon version bump (0.2.47) after `npm run patch`
-  (npm publish needs the user's npm key).

package/openspec/changes/proxy-observability/specs/observability/spec.md

@@ -1,33 +0,0 @@
-# observability — delta spec
-
-## ADDED Requirements
-
-### Requirement: Health endpoints report the version
-`GET /healthz` and `GET /health` SHALL include the running proxy version
-(from package.json) alongside the existing `ok` field.
-
-#### Scenario: Version visible remotely
-- **WHEN** a client requests `/healthz`
-- **THEN** the response contains `ok: true` and the exact npm package version
-  of the running proxy
-
-### Requirement: Peer-discovery diagnostics
-The proxy SHALL log, per torrent: an added line with file count, `private`
-flag and tracker count; every torrent-level warning (tracker rejections and
-errors surface as warnings); and each tracker announce response with the
-seeder/leecher counts returned. Logging failures MUST NOT affect playback
-(best-effort, defensive against WebTorrent internals).
-
-#### Scenario: Zero-peer torrent is explainable
-- **WHEN** a torrent sits at zero peers
-- **THEN** the log shows either the tracker's rejection/warning text or an
-  announce response with zero seeders — distinguishing "tracker refused us"
-  from "the swarm is empty"
-
-### Requirement: No SSDP listener warnings
-Port mapping SHALL NOT flood the log with `MaxListenersExceededWarning`
-regardless of how many ports one mapper maps or renews.
-
-#### Scenario: WebRTC UDP range mapping
-- **WHEN** the UDP mapper maps its 10-port range and later auto-renews it
-- **THEN** no MaxListenersExceededWarning lines appear in the log

package/openspec/changes/proxy-observability/tasks.md

@@ -1,21 +0,0 @@
-# Tasks: Proxy observability
-
-## 1. Implementation
-
-- [x] 1.1 Version in `/healthz` and `/health` (createRequire package.json in
-      server.js, passed as route dep)
-- [x] 1.2 torrent-pool.js: added-torrent line (files/private/trackers),
-      torrent `warning` logging, tracker `update` (announce seeders/leechers)
-      logging with defensive access, client-level warning logging
-- [x] 1.3 port-mapper.js: setMaxListeners(0) on the UPnP SSDP emitter after
-      the first successful map()
-- [x] 1.4 Syntax checks + healthz handler smoke test (version present)
-
-## 2. Release
-
-- [x] 2.1 CHANGELOG.md entry at 2.9.25
-- [x] 2.2 `npm run patch` (needs npm auth), then ha-addon bump 0.2.47 + push
-      (2.9.25 published by the owner — npm 2FA; addon 0.2.47 pushed after)
-- [ ] 2.3 After the addon updates: verify version via `/healthz`, watch the
-      addon log for announce lines on a real torrent, confirm no SSDP
-      warnings

package/openspec/changes/seek-debounce/design.md

@@ -1,118 +0,0 @@
-# Design: Debounce server-side seek restarts
-
-Normative — member names, constants, and edge cases as written. Read before
-coding:
-
-- `services/hls-session-manager.js`: `#ensureEncodingFor(session, index)`
-  (line ~1478 — the restart decision), the session object shape where
-  `lastRestartAt` / `pendingRestartIndex` / `encodeStartIndex` live (~883),
-  `#startEncodeRun`, `disposeSession` (must clear timers), and the constants
-  block (~36–58).
-
-## Current behaviour (what we are replacing)
-
-`#ensureEncodingFor` runs per segment request:
-
-1. Compute the look-ahead window `[head, currentSeg + MAX_LOOKAHEAD_SEGMENTS]`.
-2. In window → return (the running encode will reach it).
-3. Out of window (a seek) → if `now - lastRestartAt < RESTART_COOLDOWN_MS`,
-   skip; else `#startEncodeRun(session, index)` immediately.
-
-The cooldown is a fixed 4 s gap. Requests spaced wider than 4 s each restart
-→ ping-pong. That is the bug.
-
-## New behaviour: settle window (debounce)
-
-Keep steps 1–2. Replace step 3 with a debounce:
-
-    far request (index outside window):
-      session.seekTarget = index                       // last far index wins
-      if (!session.seekSettleTimer):
-        session.seekFirstFarAt = now()
-      else:
-        clearTimeout(session.seekSettleTimer)
-      const waited = now() - session.seekFirstFarAt
-      const delay = waited >= SEEK_SETTLE_MAX_MS ? 0
-                    : Math.min(SEEK_SETTLE_MS, SEEK_SETTLE_MAX_MS - waited)
-      session.seekSettleTimer = setTimeout(() => fireSettledSeek(session), delay)
-      return                                            // do NOT restart now
-
-    fireSettledSeek(session):
-      const target = session.seekTarget
-      session.seekSettleTimer = null
-      session.seekTarget = null
-      session.seekFirstFarAt = 0
-      if (session disposed or target == null) return
-      // Minimum gap between actual restarts (defensive; the settle already
-      // collapses bursts). If still cooling down, re-arm once for the
-      // remaining cooldown instead of restarting.
-      const sinceRestart = now() - (session.lastRestartAt ?? 0)
-      if (sinceRestart < RESTART_COOLDOWN_MS):
-        session.seekFirstFarAt = now()
-        session.seekTarget = target
-        session.seekSettleTimer = setTimeout(() => fireSettledSeek(session),
-                                             RESTART_COOLDOWN_MS - sinceRestart)
-        return
-      log(`transcode ${id} seek settle → restart at #${target}`)
-      this.#startEncodeRun(session, target)             // sets lastRestartAt
-
-Notes:
-- `timer.unref?.()` on each `setTimeout` so a pending settle never keeps the
-  process alive (mirror the codebase's other timers).
-- A far request whose `index` equals the current `seekTarget` still re-arms
-  the timer (the player is still asking for the same place — that is fine, it
-  just extends the quiet period up to the cap).
-- If, while a settle is pending, the running encode advances so a later
-  request falls back INSIDE the window, that request returns at step 2 and
-  does not touch the settle. The pending settle still fires for the recorded
-  target; that is acceptable (it restarts at a position the player recently
-  wanted). Simplicity over cleverness.
-
-## Constants (add to the constants block)
-
-    // Quiet period after a far (seek) segment request before ffmpeg is
-    // restarted at it. Further far requests within the period re-arm it, so a
-    // scrub that emits a burst of scattered requests collapses to ONE restart
-    // at the position the player ended on.
-    SEEK_SETTLE_MS = 1200
-    // Hard cap on the total settle wait measured from the first far request of
-    // a burst, so a still-moving scrubber cannot delay a real seek forever.
-    SEEK_SETTLE_MAX_MS = 2500
-
-`MAX_LOOKAHEAD_SEGMENTS` and `RESTART_COOLDOWN_MS` keep their current values;
-`RESTART_COOLDOWN_MS` is now only the floor between actual restarts.
-
-## Session state (add where lastRestartAt is initialised, ~883)
-
-    seekSettleTimer: null,   // pending settle timer handle or null
-    seekTarget: null,        // pending far segment index to restart at
-    seekFirstFarAt: 0,       // timestamp of the first far request in the burst
-
-## Disposal
-
-`disposeSession` (and any teardown that abandons a session) MUST
-`clearTimeout(session.seekSettleTimer)` and null it, so a settle cannot fire
-after disposal and restart a dead session.
-
-## Why proxy-side, not client-side (the user's original framing)
-
-The user asked for a scrubber-release debounce. On the in-page media-chrome
-control that is possible but fragile, and — decisively — it cannot cover the
-iOS **native fullscreen** player, whose scrubber the web app does not control;
-the failing session was exactly iOS. The proxy sees the segment requests from
-EVERY client (native iOS, hls.js, direct `<video>`), so debouncing the
-restart here is the one place that fixes all of them. An in-page scrubber
-debounce may still be added later as a responsiveness nicety; it is not a
-substitute and is out of scope here.
-
-## Verification
-
-- Unit-test the timing/target logic in isolation (a fake session + a fake
-  clock/`setTimeout`): a burst of far requests `367,732,369,368,370` within
-  the window collapses to a single `#startEncodeRun` at the LAST index (370),
-  and a lone later far request triggers exactly one more restart.
-- `node --check`.
-- Field: the earlier hang scenario (scrub Poirot on iOS) should now produce a
-  single `seek settle → restart` log line per scrub instead of a train of
-  `seek → restart` lines, and playback should resume after one settle + the
-  (separate, unavoidable) cold-segment wait.

package/openspec/changes/seek-debounce/proposal.md

@@ -1,59 +0,0 @@
-# Proposal: Debounce server-side seek restarts
-
-## Why
-
-Field evidence (iPhone/Safari, Poirot, 2026-07-09): after a scrub the player
-hung indefinitely. The proxy restarts ffmpeg at a requested segment when the
-request lands outside the look-ahead window (server-side seek). The native
-iOS player issued scattered segment requests after the seek —
-`367 → 732 → 369 → 368 → 370` — each 25–35 s apart. The existing guard
-(`RESTART_COOLDOWN_MS = 4000`) only suppresses restarts within 4 s of the
-last one, so with requests spaced far wider than that, EVERY scattered
-request restarted ffmpeg at a new position. ffmpeg ping-ponged between
-positions and never finished a single segment, so playback stalled at
-`currentTime` with `bufferedAhead=0` — "заглохло наглухо".
-
-The fix is the user's idea placed where every client is covered (including
-the iOS native fullscreen player, whose scrubber the web app cannot control):
-don't act on the first far request — wait for the burst to settle, then
-restart ONCE at the position the player ended on.
-
-## What Changes
-
-- Replace the fixed post-restart cooldown as the anti-thrash mechanism with a
-  **settle window**. When a segment request lands outside the look-ahead
-  window (a seek), the proxy does NOT restart immediately: it records the
-  requested index as the pending seek target and arms a short quiet-period
-  timer. Each further far request updates the target to the latest index and
-  re-arms the timer (debounce). When the quiet period elapses with no new far
-  request, ffmpeg restarts ONCE at the pending target. A hard cap bounds the
-  total wait so a genuine seek is never delayed more than a fixed budget even
-  while the scrubber is still moving.
-- Meanwhile the segment route behaves exactly as today — it long-polls and
-  the client retries — so the player simply waits out the (short) settle
-  instead of driving restarts.
-- "Last far index wins" self-corrects: if the settle resolves on the wrong
-  position (e.g. a lone probe request), the player's next request re-arms one
-  more settle — at most one extra cycle, never the old infinite ping-pong.
-
-Out of scope (documented in design.md): an optional client-side scrubber
-debounce for the in-page media-chrome control (helps responsiveness but does
-NOT cover iOS native fullscreen, so the proxy-side settle is the must-have);
-the cold-torrent piece-download and weak-host encode latency that make the
-FIRST post-seek segment slow regardless — the settle removes the infinite
-thrash, not the one-time seek latency.
-
-## Capabilities
-
-### Modified Capabilities
-
-- `seek-debounce` (server-side HLS seeking): far-segment requests are
-  debounced into a single ffmpeg restart at the settled position.
-
-## Impact
-
-- `services/hls-session-manager.js` — `#ensureEncodingFor` gains the settle
-  window; per-session settle state; `disposeSession` clears the timer;
-  constants. `RESTART_COOLDOWN_MS` is retained only as a minimum gap between
-  actual restarts.
-- Proxy release + ha-addon version bump (per release rules).

package/openspec/changes/seek-debounce/specs/seek-debounce/spec.md

@@ -1,41 +0,0 @@
-# seek-debounce — delta spec (proxy)
-
-## ADDED Requirements
-
-### Requirement: Scattered post-seek segment requests collapse to one restart
-
-When segment requests land outside the running encode's look-ahead window
-(server-side seeks), the proxy SHALL NOT restart ffmpeg on each one. It SHALL
-wait a short settle period, treating further out-of-window requests as
-re-arming the period and updating the target to the most recently requested
-index, and then restart the encoder exactly once at the settled target. A
-fixed cap SHALL bound the total settle wait so a genuine seek is not delayed
-indefinitely while the scrubber is still moving. During the settle the
-segment route behaves as before (long-poll / client retry).
-
-#### Scenario: Scrub emits a burst of scattered requests
-- **WHEN** a player, after a seek, requests several far-apart segments in
-  quick succession (e.g. 367, 732, 369, 368, 370)
-- **THEN** ffmpeg is restarted only once, at the last requested index, and
-  produces a continuous run from there — no ping-pong between positions
-
-#### Scenario: Settle resolves on the wrong position
-- **WHEN** the settled restart target turns out not to be where the player
-  ultimately needs to play (e.g. it was a lone probe request)
-- **THEN** the player's next out-of-window request arms exactly one more
-  settle and one more restart — never an unbounded restart loop
-
-#### Scenario: Request falls back inside the window
-- **WHEN** a requested segment is within the current run's look-ahead window
-- **THEN** it is served by the running encode with no restart and without
-  affecting any pending settle
-
-### Requirement: A pending settle never outlives its session
-
-When a session is disposed, any pending settle timer SHALL be cleared so it
-cannot fire and restart a disposed session.
-
-#### Scenario: Session disposed mid-settle
-- **WHEN** a session with a pending seek-settle timer is disposed (idle TTL,
-  shutdown, or teardown)
-- **THEN** the timer is cleared and no encode restart occurs afterwards

package/openspec/changes/seek-debounce/tasks.md

@@ -1,33 +0,0 @@
-# Tasks: Debounce server-side seek restarts
-
-## 1. Implementation (proxy)
-
-- [x] 1.1 Add `SEEK_SETTLE_MS = 1200` and `SEEK_SETTLE_MAX_MS = 2500` to the
-      constants block in `hls-session-manager.js`.
-- [x] 1.2 Add session state `seekSettleTimer: null`, `seekTarget: null`,
-      `seekFirstFarAt: 0` where `lastRestartAt` is initialised.
-- [x] 1.3 Rewrite the out-of-window branch of `#ensureEncodingFor` as the
-      settle/debounce (design.md): record target, arm/re-arm the timer with
-      the capped delay, restart once on fire (`#fireSettledSeek`), re-arm for
-      the cooldown remainder if still cooling down. `timer.unref?.()`.
-- [x] 1.4 `disposeSession`: clear `seekSettleTimer` and null it.
-- [x] 1.5 Restart log line: `transcode <id> seek settle → restart at segment #<target>`.
-
-## 2. Verification
-
-- [x] 2.1 Timing/target logic verified with a fake-clock replica: burst
-      `367,732,369,368,370` → one restart at 370; lone later far request →
-      exactly one more restart (900); disposal mid-settle → no restart; the
-      2.5 s cap forces a fire while the scrubber keeps moving. (Replica, not
-      the wired private method — the methods are private and `#startEncodeRun`
-      spawns ffmpeg; the wired code mirrors the replica.)
-- [x] 2.2 `node --check services/hls-session-manager.js`.
-
-## 3. Release
-
-- [ ] 3.1 CHANGELOG (proxy, next patch) + `npm run patch` (user OTP).
-- [ ] 3.2 Bump `ha-addon/torrent_tv_proxy/config.yaml` + CHANGELOG; push;
-      update the addon in HA.
-- [ ] 3.3 Field: scrub Poirot on iOS → a single `seek settle → restart` per
-      scrub (not a train of `seek → restart`), playback resumes after the
-      settle + the unavoidable cold-segment wait.

package/openspec/changes/subtitle-language/.openspec.yaml

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

package/openspec/changes/subtitle-language/proposal.md

@@ -1,50 +0,0 @@
-# Proposal: Proxy owns subtitle conversion + content-based language detection
-
-## Why
-
-Subtitle language was guessed only from the filename, so a file without a
-language code (e.g. the Enola release's `.srt`) showed "Unknown", and the
-owner specifically does not want Ukrainian and Russian confused. Reliable
-detection needs an n-gram model on the actual text — which belongs on the
-proxy (Node, node_modules, no per-browser payload, and the subtitle bytes are
-right there) rather than in the browser.
-
-## What Changes
-
-- The proxy becomes the single owner of subtitle content: `GET /api/subtitles`
-  now also serves EXTERNAL subtitle files (no `trackIndex`) — it reads the
-  file, decodes its encoding (UTF-8 or Windows-1251, common for Russian
-  `.srt`), and converts `.srt`/`.ass`/`.ssa` → WebVTT here. The browser no
-  longer converts.
-- The proxy detects the language from the full text with `franc` (n-gram /
-  trigram, MIT), restricted to a curated set of plausible subtitle languages
-  (distinguishes ru/uk/bg/sr and Latin languages; avoids short-text false
-  positives like English→Scots), and reports it in `X-Subtitle-Language`
-  (+ `X-Subtitle-Language-Name`). Embedded tracks detect from the first chunk
-  of extracted VTT.
-- The browser sets each track's language by priority: explicit code in the
-  filename / container metadata (author intent) → proxy content detection →
-  the film's audio-track language (forced-signs subs usually match the dub)
-  → Unknown.
-
-## Capabilities
-
-### New Capabilities
-
-- `subtitle-language`: proxy-side subtitle conversion, encoding handling and
-  content-based language detection.
-
-### Modified Capabilities
-
-<!-- track-selection covered embedded extraction; this extends /api/subtitles
-     to external files and adds detection. Its change is unarchived, so this
-     lands as a new capability rather than a delta. -->
-
-## Impact
-
-- proxy: new `services/subtitle-convert.js`, `services/language-detect.js`
-  (franc dep), extended `routes/api/subtitles/get.js`.
-- server: `components/loading/loading.js` fetches VTT from the proxy for
-  external subs (drops client-side conversion) and applies the language
-  priority; browser franc/alphabet detection removed.
-- Pairs with a server release; requires the ha-addon bump.