@torrent-tv/proxy 2.87.4 → 2.87.6

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

@@ -1,92 +1,92 @@
-# 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).
+# 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 +1,56 @@
-# 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.
+# 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 +1,51 @@
-# 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
+# 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 +1,40 @@
-# 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.
+# 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 +1,2 @@
-schema: spec-driven
-created: 2026-07-06
+schema: spec-driven
+created: 2026-07-06

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

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