@torrent-tv/proxy 2.89.1 → 2.89.2

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

@@ -1,49 +1,49 @@
-# 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).
+# 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 +1,33 @@
-# 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
+# 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 +1,21 @@
-# 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
+# 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 +1,118 @@
-# 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.
+# 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 +1,59 @@
-# 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).
+# 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).