@torrent-tv/proxy 2.87.10 → 2.87.12

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

@@ -1,62 +1,62 @@
-# 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).
+# 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).

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

@@ -1,47 +1,47 @@
-# 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
+# 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 +1,48 @@
-# 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).
+# 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 +1,2 @@
-schema: spec-driven
-created: 2026-07-07
+schema: spec-driven
+created: 2026-07-07

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

@@ -1,37 +1,37 @@
-# 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).
+# 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 +1,25 @@
-# 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
+# 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 +1,19 @@
-# 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
+# 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 +1,2 @@
-schema: spec-driven
-created: 2026-07-06
+schema: spec-driven
+created: 2026-07-06

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

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