@torrent-tv/proxy 2.80.18 → 2.81.0

package/CHANGELOG.md

@@ -1,3 +1,25 @@
+## 2.81.0
+
+- **Fix**: EVERY ENCODER RAN TWICE, ON EVERY RUN, SINCE 2026-09-04. Building a run and starting it were two acts, so two owners each performed the second: the session manager built a run and started it, handed it back, and the orchestrator started it again. Field logs of 08-10 September: 207 runs against 414 spawns, no exception. Only the second process was reachable — this line overwrote the reference to the first — so a stop killed one and the other ran on, measured 105 seconds past its own run's death, with eleven processes writing at once on a four-core host whose budget said three. It doubled the processor, doubled the readers of the piece store (which is the pinned-piece deadlock's own trigger), and put two writers on one file name, defeating the rename 2.80.19 had just introduced: 1105 `could not publish … ENOENT` and a fatal `bufferAppendError` on both tracks at once under 2.80.19 itself.
+  **A run exists means its process is running.** `start()` is gone; the spawn is part of construction. There is no second act for a second owner to perform, and `test/one-authority.test.js` now asks what its own name promised — it counted where a run is BUILT and never where one is STARTED, which is why it passed throughout.
+- **Fix**: The spilled pieces have a ceiling, and passing it gives disk back. `DiskTier` wrote every piece into one sparse file and answered `forget` by dropping a number from a set: the blocks stayed until the whole file went, and nothing this runtime offers punches a hole in a sparse file. Field 2026-08-31: a store holding 312-424 MB had written 14 400 MB, and the host's free space fell by every megabyte of it. `PieceDiskStore` gives each piece its own file, so removing one returns exactly its blocks; over its allowance it throws away the least recently used, and a piece being read is never the victim.
+- **Fix**: One owner of the disk, read by everything that takes any of it. Three things wrote to the same disk and each read the free space as though it were alone — segments at a quarter of free plus a 2 GB floor, both chosen by hand; spilled pieces at nothing at all; diagnostics bounded by a count and never by a size. `services/disk/DiskSpace.js` reads it once and divides, by the rule memory already uses: what is free, plus what we hold, less what everything that is not us has been seen to need. `SEGMENT_STORE_FREE_SHARE`, `SEGMENT_STORE_FALLBACK_BYTES` and the local free-space read are deleted; the torrent thread's share travels the channel it already uses and the reply says what it holds.
+- **Fix**: What goes first when the disk is short is decided by where the viewers are, not by when a directory was last read. Outputs nobody is watching, then what lies behind the earliest viewer furthest-behind-first, then what lies ahead of the furthest viewer. A segment a viewer is standing on is never taken. The idle rule stays beside it and answers the other question: material nobody needs should not sit on the owner's disk merely because there is room.
+- **Fix**: A clean exit leaves nothing of ours. The root was removed only when it happened to be empty — from the first commit of this repository, never a decision — so a directory adopted at startup, owned by no session, survived the exit and was adopted again at the next start. That loop is what made an orphan permanent, and it is why 5.0 GB of segments from sessions that had ended hours before were on the addon host on 2026-09-10. Now everything the store owns goes, which also gives the startup sweep its meaning back: what is found then is from a kill.
+- **Fix**: Every test spilled into the process working directory. They passed `spillDirectory` and the store reads `options.path`, so each wrote over the others' files.
+- **Chore**: `allowance.js` holds the rule memory and disk now share, instead of one copy per resource. 991 checks pass, biome clean; the ceiling and the double spawn were each checked by breaking them on purpose — 6 of 9 and 1 of 13 go red.
+- **Chore**: NOT yet seen in the field. What the next session must show: one ffmpeg per run in `run-state` (207 IDLE spawns and no STARTING spawns), no `could not publish … ENOENT`, a `disk:` line naming free space and each claimant's share, and `/tmp/torrent-tv-hls` empty after a clean stop.
+
+## 2.80.19
+
+- **Fix**: HALF A SEGMENT WAS SERVED TO THE PLAYER, AND THE SESSION NEVER RECOVERED. A piece was taken as finished when the NEXT number existed. That is sound for one writer walking forward and false the moment two runs share an output — which is what the plan gives an output whenever it places a second encoder, and what a one-segment interval guarantees. Field 2026-09-08: `segment-00057.mp4` was served at 2 268 361 bytes and then at 4 510 940, exactly half; `segment-00055.mp4` at 211 957 and then 2 620 617. The browser appended the half, refused the whole one for the rest of the session and repeated `bufferAppendError` to the end of the log with the picture frozen at 319.66 s.
+  **A piece's NAME is the proof now, and there is no second one.** It is written as `making-<from>-00057.mp4` — tagged with the first number of its run's stretch — and takes `segment-00057.mp4` when the encoder says on its own channel that it has closed it, which is one rename inside one directory. The `hls` branch needed nothing added: its muxer already writes through a temporary name of its own. One rule for both branches, and true whether or not this process is alive.
+- **Fix**: The last piece of every run is provable. Under the successor rule nothing followed it, so it never was — which is the resume case that held a segment for 46 s and then answered 404 to a browser that had given up.
+- **Fix**: Clearing up after a dead run is a name match against that run's own tag: no stretch to search, no bytes to judge, and no way to remove a complete piece another run closed. `services/encode/open-piece.js` did all three by guessing, and under the naming rule its guess would have removed a finished segment — the highest served name in a dead run's stretch is a piece that run closed. It is deleted, together with the session manager's own copy of it, which fetched the output's init bytes to judge a file by its contents. 135 lines of service code and 152 of tests for the guessing are gone; the manager is 83 lines shorter and 5 longer.
+- **Fix**: One owner for "this piece is closed". A set of statements was kept beside the disk and told by whoever noticed a piece being produced — the same two-owner fault 2.80.11 removed from the coverage map, one layer down. A rename cannot go out of step with itself.
+- **New**: `encode-plan on <output>` carries every term the decision was made from: `[speed=4.45x firstByte=1.26s kill=0.04s refetch=0.000s/s maxRuns=2 live=1]`. An interval says what was decided; only these say why. A decision of this plan is `delay + (index - at) / rate + madeBetween * refetch` against a deadline, so a recorded decision without the rate can be re-read and not recomputed — which is exactly what happened with the one-piece intervals of 2026-09-08, where the rate was substituted six times from the speeds the session reported elsewhere and none of them gave the answer the plan had given. A zero in the last three is a measurement nobody has taken, not a free operation, and it is printed so that reading it as free is a choice.
+- **Chore**: 965 checks pass, biome clean. NOT yet seen in the field. What the next session must show: `making-*` files present in an output's directory while it is being written and none left after it; no `bufferAppendError` following a segment served twice at different sizes; and the terms above beside every placement.
+
 ## 2.80.18
 
 - **Fix**: The `Infinity` is gone, and with it a double count I had introduced. The measured "time to a first piece" already CONTAINS one piece's encoding, and I was adding another; separated, the two scale differently — a piece costs more when encoders share the machine, a spawn does not. So a fresh encoder owes `spawn overhead + the piece at the rate in force`, a moved one owes the kill and then the same. With nothing measured the overhead is zero and a fresh encoder owes exactly one piece, which is the floor and is DERIVED rather than chosen: a piece cannot appear before it is encoded, and how fast this host encodes is measured before any viewer exists. The `Infinity` was an exception in a model that needs none. Verified by simulation over eighty ticks against the map's real shape — zero moves and zero one-piece intervals at a budget of one encoder and of three.

package/docs/encode-architecture.md

@@ -321,10 +321,25 @@ places three.
 
 ```
 encode-plan on <output>: start #58..#481, stop #?..#?
+  [speed=4.45x firstByte=1.26s kill=0.04s refetch=0.000s/s maxRuns=2 live=1]
 ```
 
-Every action with its INTERVAL, which is what a run is. Printed on any pass that
-does something — a session where nothing changes says nothing.
+Every action with its INTERVAL, which is what a run is, and then every term the
+decision was made from. Printed on any pass that does something — a session
+where nothing changes says nothing.
+
+The terms are there because an interval says WHAT was decided and only these say
+WHY. A decision of this plan is
+
+    delay + (index - at) / rate + madeBetween * refetch    against a deadline
+
+so a recorded decision without the rate can be re-read and not recomputed. That
+is not hypothetical: the one-piece intervals of 2026-09-08 were diagnosed by
+substituting the rate from the speeds the session reported elsewhere — six
+different figures, none of which reproduced the answer the plan had given.
+
+A zero in `firstByte`, `kill` or `refetch` is a measurement nobody has taken, not
+a free operation. It is printed so that reading it as free is a choice.
 
 It was missing, and its absence cost three wrong diagnoses of one field session.
 The line printed the windows, the budget and where the live runs stood; the
@@ -336,6 +351,35 @@ reasons printed beside them read as moves back and forth, so the fault was read
 as an oscillating placement three times over. An interval of one segment turns
 the protection against two encoders writing one name into a mill for processes.
 
+## What proves a segment is finished
+
+Its NAME, and there is nothing else. A piece being written is called
+`making-<from>-00042.mp4` — the tag is the first number of the stretch its run
+was given — and it takes `segment-00042.mp4` when the encoder says it has closed
+it, which it does on a channel of its own (`-segment_list pipe:3`). Making it
+servable is therefore one rename inside one directory, performed by the store
+because the store owns the disk. The `hls` branch needs nothing extra: its muxer
+writes through a temporary name of its own, so its files appear under their final
+name whole.
+
+Three things follow, and each replaced a guess:
+
+1. **a request can never reach a half-written piece.** Closure used to be
+   inferred from the NEXT number existing — sound for one writer walking forward,
+   false the moment two runs share an output, which is what the plan gives an
+   output whenever it places a second encoder. Field 2026-09-08:
+   `segment-00057.mp4` served at 2 268 361 bytes and then at 4 510 940, exactly
+   half; the browser appended the half and refused the whole for the rest of the
+   session, with the picture frozen at 319.66 s;
+2. **the last piece of a run is provable.** Under the successor rule nothing
+   followed it, so it never was — the resume case that held one segment for 46 s
+   and then answered 404;
+3. **clearing up after a dead run is a name match.** Its unfinished pieces are
+   the ones carrying its own tag: no stretch to search, no bytes to judge, and no
+   way to remove a complete piece somebody else closed. `services/encode/
+   open-piece.js` did all three of those by guessing and is gone, along with the
+   session manager's copy of it.
+
 ## What is checked
 
 `test/one-authority.test.js` holds the shape: one caller of `#startEncodeRun`,
@@ -348,3 +392,8 @@ viewer registry, the real `LiveOutputs` and the real `PriorityOrchestrator`.
 
 `test/encode-plan.test.js` holds the arithmetic, including that every encoder
 stops when nobody is watching the output.
+
+`test/segment-store.test.js` holds the naming rule: a piece under its served
+name is finished — the last one of a run included — one under a working name is
+not and cannot be reached, closing it is one rename, and clearing up after one
+run leaves every other run's work alone.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@torrent-tv/proxy",
-  "version": "2.80.18",
+  "version": "2.81.0",
   "description": "Torrent proxy client that exposes webseed-like HTTP stream endpoint.",
   "license": "GPL-3.0-or-later",
   "publishConfig": {

package/research/double-spawn-2026-09-10.md

@@ -0,0 +1,171 @@
+# Каждый кодировщик запускается дважды, и второй процесс никто не убивает
+
+Разбор восьми полевых сессий 8-10 сентября 2026: журнал прокси
+(`/data/proxy.log` + `proxy.log.1`, 188 634 строки, версии 2.80.18 и 2.80.19) и
+журнал браузера с дроплета (80 055 строк, восемь подписей сессий). Каждое
+утверждение помечено тем, откуда взято: ЗАМЕРЕНО (число из журнала), ПРОЧИТАНО
+(из исходников), ВЫВЕДЕНО (следствие двух первых).
+
+## 1. Причина: две власти вызывают `start()` на одном прогоне
+
+ПРОЧИТАНО. Прогон строится и ЗАПУСКАЕТСЯ в одном вызове:
+`EncodeOrchestrator.#placeAt` → `makeRun` → `hls-session-manager.#makeRunAt`
+(:3782) → `#startEncodeRun` (:5361), и последней строкой этой функции стоит
+`run.start(because)` (:5546). Вернувшись, оркестратор вызывает
+`run.start(because)` ещё раз (`EncodeOrchestrator.js:576`).
+
+`EncodeRun.start()` (`EncodeRun.js:360`) защиты от повторного вызова не имеет:
+строит аргументы заново, порождает второй процесс и ПЕРЕЗАПИСЫВАЕТ
+`this.#process`. Обработчики первого процесса остаются подписанными на тот же
+объект прогона.
+
+Обе строки появились 2026-09-04, в двух соседних коммитах: `a09b278` («A run is
+an object») поставила вызов в менеджере, `53785f2` («Encoders become classes») —
+в оркестраторе.
+
+ЗАМЕРЕНО, по переходам состояния за оба журнала:
+
+```
+207  IDLE --SPAWNED--> STARTING
+207  STARTING --SPAWNED--> STARTING
+```
+
+Ровно поровну. Двойной запуск происходит на КАЖДОМ прогоне без исключения: 207
+прогонов, 414 процессов ffmpeg.
+
+Ни один тест этого не ловит: в `test/encode-orchestrator.test.js` и соседних
+`makeRun` — заглушка, которая прогон не запускает, поэтому вызов в менеджере не
+исполняется ни разу.
+
+## 2. Остановка убивает только второй процесс
+
+ПРОЧИТАНО. `EncodeRun.stop()` шлёт SIGTERM в `this.#process` — то есть во
+второй. Первый не адресуем ниоткуда: ссылки на него не осталось.
+
+ЗАМЕРЕНО. Прогон `#453..#562` выхода `…grid=kf@38:video-only:v=38/copy`
+остановлен в 09:12:01.178; его ffmpeg писал в поток ошибок до **09:13:46.938 —
+105 секунд спустя**. Прогон `#463..#562` остановлен 09:12:10.204, последняя
+строка 09:13:50.038 — 100 секунд спустя. Осиротевший процесс живёт до конца
+своего отрезка, продолжая декодировать, читать из роя и писать файлы.
+
+ЗАМЕРЕНО. Число РАЗНЫХ отрезков, писавших в поток ошибок в течение одной
+секунды, на ОДНОМ выходе: 11 (09:13:31), 10 (09:13:32), 10 (09:13:34), 10
+(09:13:05). Машина — CM4, четыре ядра. Бюджет в это время печатал `maxRuns=3`, и
+машина состояний насчитывала не более трёх живых прогонов: **восемь из
+одиннадцати процессов не видел никто.**
+
+## 3. Что это ломает
+
+### 3.1. Доказательство завершённости куска обойдено
+
+Два процесса одного прогона получают ОДИН И ТОТ ЖЕ аргумент вывода —
+`making-<метка>-%05d.mp4`, где метка равна первому номеру отрезка. Метка задумана
+как имя прогона («отрезки не пересекаются, значит два живых прогона одного выхода
+начинаются с разных номеров по построению»). Для двух процессов ОДНОГО прогона
+это неверно: метка совпадает, и они пишут одно имя.
+
+ЗАМЕРЕНО: **1105 строк** `segment store: could not publish making-…: ENOENT` —
+один из двух переименовал файл, второму переименовывать нечего. По меткам: 904 на
+`making-0`, остальные разбросаны по всем выходам и всем сессиям.
+
+ВЫВЕДЕНО: это ровно та порча, ради которой 2.80.19 вводил рабочее имя — два
+писателя на одно имя. Правка не отменена, она обойдена изнутри.
+
+ЗАМЕРЕНО, что порча жива после 2.80.19: сессия `8cddc6f8` (10.09, 09:15:04) —
+`fatal: bufferAppendError` одновременно на звуке (`segment-00072.mp4`) и на
+картинке (`segment-00071.mp4`), `currentTime=712.61`. Сессия кончилась.
+
+### 3.2. Механизм имени сам по себе исправен
+
+ЗАМЕРЕНО на хосте дополнения: ffmpeg с `-f segment -segment_list pipe:3
+-segment_list_flags +live` и шаблоном `making-0-%05d.mp4` пишет в четвёртый канал
+имена `making-0-00000.mp4`, `…-00001`, `…-00002`, и файлы под этими именами лежат
+на диске. ENOENT возникает не из-за имени и не из-за канала.
+
+### 3.3. Двойное чтение из роя
+
+ВЫВЕДЕНО. Каждый процесс открывает свой `/stream` (свой `createFragmentReader`),
+поэтому читателей хранилища кусков вдвое больше, чем прогонов. Это спусковой
+крючок тупика с закреплёнными кусками, где 2026-09-07 торрент был уничтожен при
+четырёх читателях.
+
+### 3.4. Процессорное время и задержки
+
+ЗАМЕРЕНО. Ответы на опрос прогресса (тело около 500 байт): медиана 22 мс, p90
+**2229 мс**, максимум **18 852 мс**; 362 ответа из 3516 дольше двух секунд.
+ЗАМЕРЕНО. Предложение качества в те же минуты: `not offering 540p=0.10x
+480p=0.11x 360p=0.12x 240p=0.13x`.
+
+## 4. Что найдено рядом и причиной не является
+
+### 4.1. Зритель простоял 44 минуты, и ни один прибор этого не сосчитал
+
+Сессия `39c188b5` (08.09, 20:38-21:28). Зритель перемотал на 551.1 с, затем на
+579.4 с. Картинка встала на 596.8 с, `readyState=1`, и до конца сессии не
+сдвинулась: 528 одинаковых строк `decode t=596.8s frames=11787`.
+
+ЗАМЕРЕНО: буфер держал `video=[…413..549.091] [859.192..886.136]` — перемотка
+пришлась в дыру между 549.1 и 859.2. Браузер запросил за это время 283 куска, но
+класть их в 596.8 было нечего.
+
+ЗАМЕРЕНО: счётчик «сколько стояла картинка» не напечатал НИ ОДНОЙ строки за эту
+сессию, а переход в состояние ожидания случился один раз. Счётчик закрывается
+только по возобновлению, поэтому перерыв, который не кончился, не записывается
+вовсе — худший случай невидим по построению.
+
+ЗАМЕРЕНО: 42 `levelLoadError` за 48 минут при том, что прокси в те же секунды
+отдавал `index.m3u8` (17 539 байт, `fetchMs=8-10`). Обе стороны о запросе
+плейлиста говорят разное.
+
+ЗАМЕРЕНО: браузер запрашивал `/v/540/index.m3u8` и `/v/480/index.m3u8`, декодируя
+1920x1080 — hls.js по-прежнему сам ходит по ступеням при ошибках, вопреки
+закреплению.
+
+### 4.2. Куча главного потока выросла до 845 МБ за 26 секунд
+
+ЗАМЕРЕНО (10.09): 09:15:20 heap=101 МБ, 09:15:31 — 378 МБ, 09:15:35 — 589 МБ,
+09:15:46 — **813 МБ**, `rss=1940MB`. Написаны два снимка кучи процесса —
+`heap-process-…-451543040` (431 МБ, 09:09) и `heap-process-…-885628928` (845 МБ,
+09:15:44), оба в `/data`. **Их никто не открывал.** Это то самое чтение, которого
+ждёт работа о необъяснённом росте памяти.
+
+ЗАМЕРЕНО: после конца сессии куча падает до 35 МБ, а `rss` остаётся 979-981 МБ
+четыре часа подряд без единого зрителя.
+
+### 4.3. Ошибки разбора потока
+
+ЗАМЕРЕНО: 20 294 строки `missing picture in access unit` и 20 118 строк `Invalid
+NAL unit size` — 89 % журнала. Все на ветке КОПИРОВАНИЯ картинки файлов `.mp4`
+(`grid=kf@38` — 629 строк с адресом, `kf@33` — 185, `kf@46` — 94). Причина не
+установлена. Проверено, что общего состояния чтения у двух процессов нет: каждый
+запрос `/stream` создаёт свой читатель.
+
+### 4.4. Прогоны, не сделавшие ничего
+
+ЗАМЕРЕНО: 153 прогона остановлены планом, из них **68 не произвели ни одного
+куска**. Медиана жизни остановленного прогона 9636 мс, p90 26 719 мс, суммарно
+1885 секунд. Причины остановки: 83 — «standing at #N scores worse than standing
+at #M», 49 — «the film is no worse off without it». Довели свой отрезок до конца
+48 из 207.
+
+### 4.5. Мелочи, каждая с местом
+
+1. Поле `live=` в строке плана печатается пустым 89 раз из 211 (`maxRuns=3 live=`).
+2. `/tmp/torrent-tv-hls` — 5,0 ГБ готовых кусков от сессий, кончившихся часами
+   раньше; 3272 файла в десяти каталогах. Ничего не подметает.
+3. `/data` — 3,3 ГБ, из них слепок памяти на 4,4 ГБ от 07.09 и 365 МБ снимков
+   кучи.
+4. Предложение качества в первую секунду сессии переворачивается: 19:39:40.568
+   `not offering 1080p=0.86x (offering 720p 540p 480p 360p 240p)`, 19:39:41.058
+   `not offering 720p=0.24x … (offering 1080p)`. Первое читает копируемую картинку
+   как перекодирование.
+
+## 5. Чего этот разбор НЕ устанавливает
+
+1. почему ffmpeg на ветке копирования выдаёт ошибки разбора — связь с двойным
+   запуском не показана;
+2. что именно держит 945 МБ резидентной памяти при куче в 35 МБ — снимки есть,
+   они не прочитаны;
+3. почему браузер сообщает `levelLoadError`, когда прокси отдал плейлист без
+   ошибки;
+4. откуда в буфере взялся оторванный остров 859..886 с.

package/services/disk/DiskSpace.js

@@ -0,0 +1,146 @@
+/**
+ * @file One owner of the disk, read by everything that takes any of it.
+ *
+ * Three things on this proxy write to the same disk and, until now, each
+ * decided for itself how much it could take:
+ *
+ *   - the segments an encoder produces, bounded by a quarter of what was free
+ *     plus a floor of 2 GB, both numbers chosen out of nothing;
+ *   - the pieces the memory store spills, bounded by nothing at all — 14 400 MB
+ *     written in one fifty-minute viewing, field 2026-08-31;
+ *   - the diagnostics we keep on purpose (core dumps, heap snapshots, packet
+ *     captures), each bounded by a COUNT and none by a size: on the addon host
+ *     two dumps and five snapshots came to 3.2 GB.
+ *
+ * Each read the free space as though it were the only claimant, so three
+ * ceilings each stood for the whole disk. This is the one place that reads it,
+ * and what it hands out is a share.
+ *
+ * THE RULE IS THE ONE MEMORY ALREADY USES, on the other reading: what is free
+ * now, plus what we already hold, less what everything that is not us has been
+ * seen to need. Nothing is a fraction chosen by hand.
+ */
+
+import { OtherDemand, divideAllowance } from "../piece-store/allowance.js";
+
+/**
+ * A consumer of the disk.
+ *
+ * @typedef {object} DiskConsumer
+ * @property {string} name - What it is called in the reading.
+ * @property {() => number} held - What it holds right now, in bytes.
+ * @property {() => number} wanted - What it would take if it could. A consumer
+ *   that cannot say asks for what it holds, which is the honest statement of a
+ *   thing that only grows when something arrives.
+ * @property {(allowanceBytes: number) => void} allow - Told its share.
+ */
+
+export class DiskSpace {
+  /** @type {Map<string, DiskConsumer>} */
+  #consumers = new Map();
+
+  #otherDemand = new OtherDemand();
+
+  #readFree;
+
+  #logger;
+
+  /** The last division, for the reading. @type {{ name: string, held: number, allowed: number }[]} */
+  #last = [];
+
+  #freeBytes = 0;
+
+  /**
+   * @param {object} params
+   * @param {() => Promise<number | null>} params.readFree - What the machine
+   *   says is free on the disk these consumers share.
+   * @param {{ info: (line: string) => void, warn?: (line: string) => void }} [params.logger]
+   */
+  constructor({ readFree, logger = null }) {
+    this.#readFree = readFree;
+    this.#logger = logger;
+  }
+
+  /**
+   * Register a consumer. Registering twice under one name replaces it.
+   *
+   * @param {DiskConsumer} consumer
+   * @returns {void}
+   */
+  register(consumer) {
+    this.#consumers.set(consumer.name, consumer);
+  }
+
+  /**
+   * @param {string} name
+   * @returns {void}
+   */
+  forget(name) {
+    this.#consumers.delete(name);
+  }
+
+  /**
+   * Read the disk, divide it, and tell each consumer its share.
+   *
+   * Called on the same timer that revises memory: a disk that fills while a
+   * film is playing must lower the ceilings, not keep ones taken when it was
+   * empty. That is the mistake memory made until 2026-08-28, and every disk
+   * ceiling on this proxy made until now.
+   *
+   * @returns {Promise<{ freeBytes: number, allowanceBytes: number, shares: { name: string, held: number, allowed: number }[] }>}
+   */
+  async revise() {
+    const consumers = [...this.#consumers.values()];
+    if (consumers.length === 0) {
+      return { freeBytes: 0, allowanceBytes: 0, shares: [] };
+    }
+    const held = consumers.reduce((sum, consumer) => sum + Math.max(0, consumer.held()), 0);
+    const free = await this.#readFree();
+    // WITHOUT A READING, NOTHING IS ALLOWED TO GROW. A disk whose free space
+    // cannot be read is not a disk with room; answering "unbounded" there is how
+    // the spill file came to have no limit in the first place.
+    this.#freeBytes = Number.isFinite(free) && free !== null ? Math.max(0, free) : 0;
+    const reserve = this.#otherDemand.note(this.#freeBytes, held);
+    const allowance = Math.max(0, this.#freeBytes + held - reserve);
+    const shares = divideAllowance(
+      consumers.map((consumer) => Math.max(0, consumer.wanted())),
+      allowance
+    );
+    this.#last = consumers.map((consumer, position) => ({
+      name: consumer.name,
+      held: consumer.held(),
+      allowed: shares[position]
+    }));
+    for (const [position, consumer] of consumers.entries()) {
+      consumer.allow(shares[position]);
+    }
+    return { freeBytes: this.#freeBytes, allowanceBytes: allowance, shares: this.#last };
+  }
+
+  /**
+   * One line: what the disk has, what each consumer holds, and what it may.
+   *
+   * Said because "why is there no room" is otherwise a question no log can
+   * answer — the three ceilings were computed in three places and none of them
+   * was printed beside the others.
+   *
+   * @returns {string}
+   */
+  describe() {
+    if (this.#last.length === 0) {
+      return "disk: nothing has claimed any yet";
+    }
+    const parts = this.#last.map(
+      (share) => `${share.name} ${megabytes(share.held)} of ${megabytes(share.allowed)}`
+    );
+    return `disk: ${megabytes(this.#freeBytes)} free; ${parts.join(", ")}`;
+  }
+}
+
+/**
+ * @param {number} bytes
+ * @returns {string}
+ */
+function megabytes(bytes) {
+  return `${Math.round(Math.max(0, bytes) / (1024 * 1024))}MB`;
+}

package/services/disk/wire.js

@@ -0,0 +1,60 @@
+/**
+ * @file Who takes disk, and how each of them is told its share.
+ *
+ * Kept apart from the owner because the owner knows nothing about this proxy —
+ * it reads a number, divides it and hands out shares — and kept out of the
+ * session manager because a list of claimants is not a fact about a session.
+ *
+ * Two claimants today. The diagnostics are a third and are not here yet: they
+ * are bounded by a COUNT and never by a size, which on the addon host let two
+ * core dumps and five heap snapshots come to 3.2 GB, and they cannot simply be
+ * thrown away when space is short — a dump is the only evidence of the death it
+ * records. That needs a rule of its own.
+ */
+
+import { DiskSpace } from "./DiskSpace.js";
+
+/**
+ * Build the owner of the disk and register everything that takes any of it.
+ *
+ * @param {object} params
+ * @param {{ root: string, stats: () => { bytes: number } }} params.segmentStore
+ * @param {{ spilledBytes?: number, allowSpillBytes?: (bytes: number) => unknown }} [params.torrentPool]
+ * @param {(directory: string) => Promise<number | null>} params.readFree
+ * @param {{ info: Function, warn?: Function }} [params.logger]
+ * @returns {{ revise: () => Promise<unknown>, segmentBytes: () => number, describe: () => string }}
+ *   What the segments may hold is asked for rather than pushed: zero until the
+ *   first revision, and zero stops growth rather than licensing it.
+ */
+export function wireDiskSpace({ segmentStore, torrentPool, readFree, logger }) {
+  const space = new DiskSpace({ readFree: () => readFree(segmentStore.root), logger });
+  let segmentBytes = 0;
+  space.register({
+    name: "segments",
+    held: () => segmentStore.stats().bytes,
+    // The whole of every film anybody is watching. There is no smaller honest
+    // answer, so it asks for everything and is cut in proportion like the rest.
+    wanted: () => Number.MAX_SAFE_INTEGER,
+    allow: (bytes) => {
+      segmentBytes = bytes;
+    }
+  });
+  if (typeof torrentPool?.allowSpillBytes === "function") {
+    // The pieces the memory store spills. They live on the torrent thread, so
+    // the share travels the channel that already carries everything else, and
+    // the reply says what they hold — one exchange, both directions.
+    space.register({
+      name: "spilled pieces",
+      held: () => torrentPool.spilledBytes ?? 0,
+      wanted: () => Number.MAX_SAFE_INTEGER,
+      allow: (bytes) => {
+        void torrentPool.allowSpillBytes?.(bytes);
+      }
+    });
+  }
+  return {
+    revise: () => space.revise(),
+    segmentBytes: () => segmentBytes,
+    describe: () => space.describe()
+  };
+}

package/services/encode/EncodeRun.js

@@ -181,9 +181,11 @@ export class EncodeRun {
    * @param {{ info: (line: string) => void, warn: (line: string) => void, error?: (line: string) => void }} params.logger
    * @param {() => number} [params.now]
    * @param {(ended: RunEnded) => void} [params.onEnded]
-   * @param {(name: string) => void} [params.onClosed] - Called with the file name
-   *   of every piece the encoder has FINISHED writing, as the encoder itself
-   *   names it on its own channel.
+   * @param {(name: string) => string | null} [params.onClosed] - Called with the
+   *   WORKING name of every piece the encoder has finished writing, as the
+   *   encoder itself names it on its own channel, and answers with the name that
+   *   piece is served under — because making it servable is a rename, and only
+   *   whoever owns the disk can perform one.
    * @param {(progress: { processedSeconds: number | null, speed: string | null }) => void} [params.onProgress]
    *   Called for every `-progress` report. Seconds count from the START OF THIS
    *   RUN on both branches — neither `-output_ts_offset` nor `-copyts` changes
@@ -199,6 +201,9 @@ export class EncodeRun {
    *   kept so a failure can quote what produced it.
    * @param {boolean} [params.usesExplicitCuts] - Whether this run cuts at times
    *   it was given, which decides how a segment is judged finished.
+   * @param {string} params.because - Why this encoder is being put on the
+   *   machine, in words. Recorded with the argument list: a start whose cause is
+   *   not written down cannot be told from any other when several runs exist.
    * @param {(name: string) => number | null} [params.indexOfName] - The number
    *   a closed piece's name carries. How a piece is named belongs to the format
    *   that writes it, so it arrives as a plain function rather than this class
@@ -220,7 +225,8 @@ export class EncodeRun {
     inputUnavailable,
     argsDescribed = "",
     usesExplicitCuts = false,
-    indexOfName
+    indexOfName,
+    because = "no reason was given"
   }) {
     this.address = address;
     this.encoder = encoder;
@@ -242,6 +248,9 @@ export class EncodeRun {
     this.indexOfName = typeof indexOfName === "function" ? indexOfName : () => null;
     /** The last thing ffmpeg said on stderr, which is what a failure is explained by. */
     this.lastError = "";
+    // EXISTING IS RUNNING. There is no moment at which a built run is not yet a
+    // process, so there is no second act for two owners to perform.
+    this.#begin(because);
   }
 
   /** @returns {string} */
@@ -346,7 +355,22 @@ export class EncodeRun {
   }
 
   /**
-   * Start it, and say why it is being started.
+   * Put the process on the machine, and say why.
+   *
+   * PRIVATE, AND CALLED ONCE, from the constructor. It was public until
+   * 2026-09-10, and two places called it: the session manager built a run and
+   * started it, then handed it back to the orchestrator, which started it
+   * again. Every run of every session therefore had TWO ffmpeg processes on one
+   * output writing one set of names — 207 runs against 414 spawns in the field
+   * logs of 08-10 September, without a single exception. Only the second was
+   * reachable afterwards, because this line overwrote the reference to the
+   * first, so `stop` killed one and the other ran on: measured 105 seconds past
+   * its own run's death, eleven processes writing at once on a four-core host
+   * whose budget said three.
+   *
+   * The guard against that is not a check but the absence of a second act: a
+   * run exists means its process is running, so there is nothing anybody can
+   * call twice.
    *
    * The reason is not decoration: a start whose cause is not recorded cannot be
    * told from any other start when several runs exist at once, and the argument
@@ -355,7 +379,7 @@ export class EncodeRun {
    *
    * @param {string} because
    */
-  start(because) {
+  #begin(because) {
     const args = this.buildArgs();
     this.#startedAt = this.now();
     this.logger.info(
@@ -473,8 +497,13 @@ export class EncodeRun {
       if (name.length === 0) {
         continue;
       }
+      // ITS SERVED NAME, which is what whoever owns the disk gives it in answer.
+      // ffmpeg writes a piece under a working name and reports that; the piece
+      // becomes servable by being renamed, and everything below works in the
+      // name a request can actually ask for.
+      const served = this.onClosed(name) ?? name;
       if (!this.#stopping) {
-        this.#provenName = name;
+        this.#provenName = served;
       }
       // WHAT THIS RUN HAS MADE IS THIS RUN'S OWN FACT, and this channel is where
       // it learns it. It used to be told from outside, by whoever listed the
@@ -484,11 +513,10 @@ export class EncodeRun {
       // (483 segment(s))", having produced none of them, and its head therefore
       // described somebody else's work. Both the claim it holds and the cleanup
       // after it read that head.
-      const index = this.indexOfName(name);
+      const index = this.indexOfName(served);
       if (Number.isInteger(index)) {
         this.noteProduced(index);
       }
-      this.onClosed(name);
     }
   }