@torrent-tv/proxy 2.101.23 → 2.101.25

package/package.json

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

package/routes/api/client-logs/post.js

@@ -63,10 +63,10 @@ function sanitizeLine(value) {
  *
  * @param {import("fastify").FastifyRequest} req
  * @param {import("fastify").FastifyReply} reply
- * @param {{ clientLogs: { write: (session: object, lines: string[]) => void } | null }} deps
+ * @param {{ clientLogs: { write: (session: object, lines: string[]) => void } | null, viewerRequests?: object }} deps
  * @returns {Promise<unknown>}
  */
-export async function handleApiClientLogsPost(req, reply, { clientLogs }) {
+export async function handleApiClientLogsPost(req, reply, { clientLogs, viewerRequests }) {
   const body = req.body && typeof req.body === "object" && !Array.isArray(req.body) ? req.body : {};
   const session = {
     sessionId: safeString(body.sessionId, MAX_SID_LEN) || "unknown",
@@ -89,5 +89,18 @@ export async function handleApiClientLogsPost(req, reply, { clientLogs }) {
   if (lines.length > 0) {
     clientLogs?.write(session, lines);
   }
+  for (const row of rows) {
+    const message = row && typeof row.msg === "string" ? row.msg : "";
+    const match = /^\[first-frame-observation\] consumer=([^ ]+) generation=(\d+) waitId=([^ ]+) wait=(\d+) audioReady=(true|false) elapsedMs=([\d.]+)$/.exec(message);
+    if (match) {
+      const elapsedMs = Number(match[6]);
+      if (match[1].length <= 64 && Number.isSafeInteger(Number(match[2])) && match[3].length <= 256 &&
+          Number.isSafeInteger(Number(match[4])) && match[5] === "true" &&
+          Number.isFinite(elapsedMs) && elapsedMs >= 0) {
+        viewerRequests?.noteFirstFrameObservation?.({ consumerId: match[1], generation: Number(match[2]),
+          waitId: match[3], wait: Number(match[4]), elapsedMs });
+      }
+    }
+  }
   return reply.code(204).send();
 }

package/routes/api/sources/files/get.js

@@ -15,14 +15,15 @@ import { logger } from "../../../../utils/logger.js";
  * @param {import("fastify").FastifyReply} reply
  * @param {{
  *   sourceRegistry: ReturnType<import("../../../../store/source-registry.js").createSourceRegistry>,
- *   torrentPool: import("../../../../services/torrent/torrent-pool.js").TorrentPool
+ *   torrentPool: import("../../../../services/torrent/torrent-pool.js").TorrentPool,
+ *   viewerRequests?: object
  * }} deps
  * @returns {Promise<void>}
  */
 
 const CANCELLED = Symbol("cancelled");
 
-export async function handleApiSourceFilesGet(req, reply, { sourceRegistry, torrentPool, viewers }) {
+export async function handleApiSourceFilesGet(req, reply, { sourceRegistry, torrentPool, viewers, viewerRequests }) {
   const sourceKey = typeof req.params?.sourceKey === "string" ? req.params.sourceKey.trim() : "";
   if (!sourceKey) {
     return reply.code(400).send({ error: "sourceKey is required." });
@@ -72,13 +73,21 @@ export async function handleApiSourceFilesGet(req, reply, { sourceRegistry, torr
   }
   const consumerId = typeof req.query?.consumerId === "string" ? req.query.consumerId.trim() : "";
   if (consumerId) viewers?.visibleFiles(consumerId, sourceKey, contents.items.map(item => item.fileIndex));
+  const generationRaw = typeof req.query?.generation === "string" ? req.query.generation : "";
+  const generation = generationRaw !== "" && /^\d+$/.test(generationRaw) ? Number(generationRaw) : null;
+  const files = contents.files().map(file => {
+    if (!consumerId || !Number.isSafeInteger(generation) || file.kind !== "video" || file.excludedReason) return file;
+    const waitEstimate = viewerRequests?.waitEstimateForFile?.({ consumerId, generation, sourceKey,
+      fileIndex: file.fileIndex, fileName: file.relativePath ?? file.name, fileLength: file.length }) ?? null;
+    return waitEstimate ? { ...file, waitEstimate } : file;
+  });
   return reply.send({
     name: torrent.name ?? "",
     infoHash: torrent.infoHash ?? "",
     // In the order a person reads them — by folder, then by name, with runs of
     // digits compared as numbers. A torrent's own order is whatever the tool
     // that made it chose, and it is routinely by size.
-    files: contents.files(),
+    files,
     // The pictures, each with what belongs to it. By index, because the files
     // themselves are in the list above and saying them twice is how two copies
     // of one fact start.

package/routes/api/sources/stats/get.js

@@ -13,11 +13,12 @@ import { logger } from "../../../../utils/logger.js";
  * @param {import("fastify").FastifyReply} reply
  * @param {{
  *   sourceRegistry: ReturnType<import("../../../../store/source-registry.js").createSourceRegistry>,
- *   torrentPool: import("../../../../services/torrent/torrent-pool.js").TorrentPool
+ *   torrentPool: import("../../../../services/torrent/torrent-pool.js").TorrentPool,
+ *   viewerRequests?: object
  * }} deps
  * @returns {Promise<void>}
  */
-export async function handleApiSourceStatsGet(req, reply, { sourceRegistry, torrentPool }) {
+export async function handleApiSourceStatsGet(req, reply, { sourceRegistry, torrentPool, viewerRequests }) {
   const sourceKey = typeof req.params.sourceKey === "string" ? req.params.sourceKey.trim() : "";
   if (!sourceKey) {
     return reply.code(400).send({ error: "sourceKey is required." });
@@ -28,6 +29,19 @@ export async function handleApiSourceStatsGet(req, reply, { sourceRegistry, torr
     return reply.code(404).send({ error: "Source key was not found." });
   }
 
+  const fileIndexRaw = typeof req.query.fileIndex === "string" ? req.query.fileIndex : "";
+  const fileIndex = fileIndexRaw !== "" && /^\d+$/.test(fileIndexRaw) ? Number(fileIndexRaw) : null;
+  const consumerId = typeof req.query.consumer === "string" ? req.query.consumer : "";
+  const generationRaw = typeof req.query.generation === "string" ? req.query.generation : "";
+  const generation = generationRaw !== "" && /^\d+$/.test(generationRaw) ? Number(generationRaw) : null;
+  const requestedFileName = typeof req.query.fileName === "string" ? req.query.fileName : "";
+  const requestedFileLength = typeof req.query.fileLength === "string" && /^\d+$/.test(req.query.fileLength)
+    ? Number(req.query.fileLength) : null;
+  const initialEstimate = () => consumerId && Number.isSafeInteger(generation) && Number.isSafeInteger(fileIndex)
+    ? viewerRequests?.waitEstimateForFile?.({ consumerId, generation, sourceKey, fileIndex,
+      fileName: requestedFileName, fileLength: requestedFileLength }) ?? null
+    : null;
+
   let torrent;
   try {
     torrent = torrentPool.knownTorrent(sourceKey);
@@ -37,18 +51,18 @@ export async function handleApiSourceStatsGet(req, reply, { sourceRegistry, torr
     return reply.code(500).send({ error: `Failed to load torrent: ${message}` });
   }
   if (!torrent) {
-    return reply.code(202).send({ pending: true });
+    const waitEstimate = initialEstimate();
+    return reply.code(202).send({ pending: true, ...(waitEstimate ? { waitEstimate } : {}) });
   }
 
-  const fileIndexRaw = typeof req.query.fileIndex === "string" ? req.query.fileIndex : "";
-  const fileIndex = fileIndexRaw !== "" && /^\d+$/.test(fileIndexRaw) ? Number(fileIndexRaw) : null;
-
-
   // Awaited: with the torrent on its own thread this is a round trip, not a
   // local lookup. Without the await the reply was the pending promise itself,
   // which serialises to `{}` — the empty stats seen in the field 2026-08-02.
   const stats = await torrentPool.getFileStats(torrent, fileIndex);
-  if (stats?.pending || !stats) return reply.code(202).send({ pending: true });
+  if (stats?.pending || !stats) {
+    const waitEstimate = initialEstimate();
+    return reply.code(202).send({ pending: true, ...(waitEstimate ? { waitEstimate } : {}) });
+  }
 
   // Diagnostic: surface the real swarm state per poll so a cold-start download
   // stall (0 peers / header not advancing → playback-plan blocks on the codec
@@ -121,5 +135,9 @@ export async function handleApiSourceStatsGet(req, reply, { sourceRegistry, torr
     `file=${filePct} header=${header}${detail}`
   );
 
-  return reply.send(stats);
+  const waitEstimate = consumerId && Number.isSafeInteger(generation)
+    ? viewerRequests?.waitEstimateForSource?.({ consumerId, generation, sourceKey, fileIndex,
+      fileName: torrent.files?.[fileIndex]?.name ?? requestedFileName, fileLength: requestedFileLength, stats }) ?? null
+    : null;
+  return reply.send(waitEstimate ? { ...stats, waitEstimate } : stats);
 }

package/server.js

@@ -1406,10 +1406,11 @@ export async function startProxyServer({
     return handleApiSourcesPost(req, reply, { sourceRegistry, viewers: outputParts.viewers });
   });
   app.get("/api/sources/:sourceKey/stats", async (req, reply) =>
-    handleApiSourceStatsGet(req, reply, { sourceRegistry, torrentPool })
+    handleApiSourceStatsGet(req, reply, { sourceRegistry, torrentPool, viewerRequests: outputParts.viewerRequests })
   );
   app.get("/api/sources/:sourceKey/files", async (req, reply) =>
-    handleApiSourceFilesGet(req, reply, { sourceRegistry, torrentPool, viewers: outputParts.viewers })
+    handleApiSourceFilesGet(req, reply, { sourceRegistry, torrentPool, viewers: outputParts.viewers,
+      viewerRequests: outputParts.viewerRequests })
   );
   app.get("/api/sources/:sourceKey/files/:fileIndex/fingerprint", async (req, reply) =>
     handleApiSourceFingerprintGet(req, reply, {
@@ -1463,7 +1464,7 @@ export async function startProxyServer({
     ? createClientLogFiles(logFile)
     : createClientLogConsole((message) => logger.info(message));
   app.post("/api/client-logs", async (req, reply) =>
-    handleApiClientLogsPost(req, reply, { clientLogs })
+    handleApiClientLogsPost(req, reply, { clientLogs, viewerRequests: outputParts.viewerRequests })
   );
   app.post("/api/playback-plan", async (req, reply) =>
     handleApiPlaybackPlanPost(req, reply, { playbackPlanner, viewers: outputParts.viewers })

package/services/encode/LocalObservations.js

@@ -85,8 +85,11 @@ export class LocalObservations {
   /** @type {() => number} */
   #now;
 
-  /** @type {{ speed: Record<string, object[]>, rates: Record<string, object[]>, preparation: Record<string, object[]> }} */
-  #entries = { speed: {}, rates: {}, preparation: {} };
+  /** @type {Set<string>} */
+  #configurations = new Set();
+
+  /** @type {{ speed: Record<string, object[]>, rates: Record<string, object[]>, preparation: Record<string, object[]>, firstFrame: Record<string, object[]> }} */
+  #entries = { speed: {}, rates: {}, preparation: {}, firstFrame: {} };
 
   /**
    * @param {object} params
@@ -152,6 +155,7 @@ export class LocalObservations {
    * @returns {void}
    */
   load(currentConfigurations) {
+    this.#configurations = new Set(currentConfigurations);
     if (!this.#filePath) {
       return;
     }
@@ -168,11 +172,14 @@ export class LocalObservations {
     const allowed = new Set(currentConfigurations);
     let kept = 0;
     let dropped = 0;
-    for (const kind of ["speed", "rates", "preparation"]) {
+    const firstFrameKey = this.#firstFrameKey();
+    for (const kind of ["speed", "rates", "preparation", "firstFrame"]) {
       const section = raw.entries[kind] && typeof raw.entries[kind] === "object" ? raw.entries[kind] : {};
       for (const [key, readings] of Object.entries(section)) {
-        const configuration = key.split("|")[0];
-        if (!allowed.has(configuration) || !Array.isArray(readings)) {
+        const matches = kind === "firstFrame"
+          ? key === firstFrameKey
+          : allowed.has(key.split("|")[0]);
+        if (!matches || !Array.isArray(readings)) {
           dropped += 1;
           continue;
         }
@@ -256,6 +263,75 @@ export class LocalObservations {
     this.#save();
   }
 
+  /**
+   * Keep a browser-measured wait outcome with the source and link readings
+   * visible before the container was inspected. These readings are useful
+   * only on the encoder configurations present on this host.
+   *
+   * @param {{ seconds: number, features: object }} params
+   * @returns {void}
+   */
+  noteFirstFrame({ seconds, features }) {
+    if (!Number.isFinite(seconds) || seconds < 0 || !features || typeof features !== "object") return;
+    const key = this.#firstFrameKey();
+    const readings = [...(this.#entries.firstFrame[key] ?? []), {
+      seconds,
+      extension: typeof features.extension === "string" ? features.extension : "",
+      fileLength: positive(features.fileLength),
+      downloadSpeed: nonNegative(features.downloadSpeed),
+      linkMbps: nonNegative(features.linkMbps),
+      headerRemaining: nonNegative(features.headerRemaining),
+      peers: nonNegative(features.peers),
+      at: this.#now()
+    }].slice(-READINGS_KEPT);
+    this.#entries.firstFrame[key] = readings;
+    this.#save();
+  }
+
+  /**
+   * Predict this host's first-frame wait from the closest measured start with
+   * the same media suffix. Distance is the sum of squared log-ratios for the
+   * independent measured inputs; it does not mix bytes, bit rates and peers
+   * in their raw units.
+   *
+   * @param {object} features
+   * @returns {number | null}
+   */
+  firstFrameSeconds(features) {
+    if (!features || typeof features !== "object") return null;
+    const readings = this.#entries.firstFrame[this.#firstFrameKey()] ?? [];
+    const candidates = readings.filter(reading => reading.extension === (features.extension ?? ""));
+    if (candidates.length === 0) return null;
+    const dimensions = ["fileLength", "downloadSpeed", "linkMbps", "headerRemaining", "peers"];
+    const scales = new Map(dimensions.map(key => [key, median(candidates
+      .map(reading => nonNegative(reading[key]))
+      .filter(value => value !== null && value > 0))]));
+    let best = null;
+    for (const reading of candidates) {
+      let distance = 0;
+      let used = 0;
+      for (const key of dimensions) {
+        const scale = scales.get(key);
+        const current = nonNegative(features[key]);
+        const previous = nonNegative(reading[key]);
+        if (scale === null || current === null || previous === null) continue;
+        const difference = Math.log1p(current / scale) - Math.log1p(previous / scale);
+        distance += difference * difference;
+        used += 1;
+      }
+      if (used === 0) continue;
+      distance /= used;
+      if (!best || distance < best.distance || (distance === best.distance && reading.at > best.reading.at)) {
+        best = { distance, reading };
+      }
+    }
+    return best?.reading.seconds ?? null;
+  }
+
+  #firstFrameKey() {
+    return `firstFrame:${[...this.#configurations].sort().join("||")}`;
+  }
+
   /**
    * The slowest this mode has been seen running alone on comparable material,
    * or null where nothing comparable has been seen.
@@ -349,6 +425,27 @@ export class LocalObservations {
   }
 }
 
+/** @param {unknown} value @returns {number | null} */
+function positive(value) {
+  const number = Number(value);
+  return Number.isFinite(number) && number > 0 ? number : null;
+}
+
+/** @param {unknown} value @returns {number | null} */
+function nonNegative(value) {
+  if (value === null || value === undefined || value === "") return null;
+  const number = Number(value);
+  return Number.isFinite(number) && number >= 0 ? number : null;
+}
+
+/** @param {number[]} values @returns {number | null} */
+function median(values) {
+  if (values.length === 0) return null;
+  const sorted = [...values].sort((left, right) => left - right);
+  const middle = Math.floor(sorted.length / 2);
+  return sorted.length % 2 === 0 ? (sorted[middle - 1] + sorted[middle]) / 2 : sorted[middle];
+}
+
 /**
  * What an observation of an encode is filed as having been made FROM.
  *

package/services/server/ViewerRequests.js

@@ -60,6 +60,8 @@ export class ViewerRequests {
   #host;
   /** @type {WeakMap<object, Map<string, object>>} */
   #rateStateBySession = new WeakMap();
+  /** @type {Map<string, { consumerId: string, generation: number, fileIndex: number | null, waitId: string, features: object, updatedAt: number, revision: number, observedWaits: Set<number> }>} */
+  #earlyWaits = new Map();
   /**
    * What the start forecasts cost, said once a minute: how many there were,
    * their time on the main thread, and for each track whether the times of its
@@ -97,6 +99,131 @@ export class ViewerRequests {
     this.#host = host;
   }
 
+  /**
+   * Attach a host-matched estimate to the file list before the viewer chooses
+   * a file, so the original action need not wait for a torrent-worker round trip.
+   *
+   * @param {{ consumerId: string, generation: number, sourceKey: string, fileIndex: number, fileName: string, fileLength: number }} params
+   * @returns {object | null}
+   */
+  waitEstimateForFile({ consumerId, generation, sourceKey, fileIndex, fileName, fileLength }) {
+    if (!consumerId || !Number.isSafeInteger(generation) || typeof sourceKey !== "string" ||
+        !Number.isSafeInteger(fileIndex) || fileIndex < 0) return null;
+    const waitId = `${sourceKey}:${fileIndex}:${generation}`;
+    const key = `${consumerId}:${waitId}`;
+    const extension = typeof fileName === "string" ? fileName.split(".").at(-1)?.toLowerCase() ?? "" : "";
+    const features = {
+      extension,
+      fileLength,
+      downloadSpeed: null,
+      linkMbps: this.#host.viewers.get(consumerId)?.linkReading()?.linkMbps,
+      headerRemaining: null,
+      peers: null
+    };
+    const current = this.#earlyWaits.get(key);
+    if (current?.waitId === waitId && current.hasSourceObservation) {
+      const seconds = this.#host.firstFrameSecondsOf?.(current.features) ?? null;
+      if (!Number.isFinite(seconds) || seconds < 0) return null;
+      return { version: 1, waitId, revision: current.revision, remainingSeconds: seconds, ageMs: 0 };
+    }
+    const sameWait = current?.waitId === waitId;
+    const revision = sameWait ? current.revision : 0;
+    const context = this.#setEarlyWait({ consumerId, generation, fileIndex, waitId, features, revision, current });
+    const changed = this.#recordEarlyWaitSnapshot(context, features);
+    if (sameWait && changed) context.revision += 1;
+    this.#pruneEarlyWaits();
+    const seconds = this.#host.firstFrameSecondsOf?.(features) ?? null;
+    if (!Number.isFinite(seconds) || seconds < 0) return null;
+    return { version: 1, waitId, revision, remainingSeconds: seconds, ageMs: 0 };
+  }
+
+  /**
+   * Keep the measurements available before the container is inspected and
+   * predict the complete first-frame wait from this host's earlier outcomes.
+   *
+   * @param {{ consumerId: string, generation: number, sourceKey: string, fileIndex: number | null, fileName?: string, fileLength?: number | null, stats?: object }} params
+   * @returns {object | null}
+   */
+  waitEstimateForSource({ consumerId, generation, sourceKey, fileIndex, fileName = "", fileLength = null, stats = {} }) {
+    if (!consumerId || !Number.isSafeInteger(generation) || typeof sourceKey !== "string") return null;
+    const waitId = `${sourceKey}:${fileIndex ?? "all"}:${generation}`;
+    const key = `${consumerId}:${waitId}`;
+    const extension = typeof fileName === "string" ? fileName.split(".").at(-1)?.toLowerCase() ?? "" : "";
+    const features = {
+      extension,
+      fileLength: Number.isFinite(stats?.fileLength) && stats.fileLength > 0
+        ? stats.fileLength : fileLength,
+      downloadSpeed: stats?.downloadSpeed,
+      linkMbps: this.#host.viewers.get(consumerId)?.linkReading()?.linkMbps,
+      headerRemaining: Number.isFinite(stats?.headerBytes) && Number.isFinite(stats?.headerDownloadedBytes)
+        ? Math.max(0, stats.headerBytes - stats.headerDownloadedBytes) : null,
+      peers: stats?.connectedPeers ?? stats?.numPeers
+    };
+    const current = this.#earlyWaits.get(key);
+    const revision = current?.waitId === waitId ? current.revision + 1 : 0;
+    const context = this.#setEarlyWait({ consumerId, generation, fileIndex, waitId, features, revision, current,
+      sourceObserved: true });
+    this.#recordEarlyWaitSnapshot(context, features);
+    this.#pruneEarlyWaits();
+    const seconds = this.#host.firstFrameSecondsOf?.(features) ?? null;
+    if (!Number.isFinite(seconds) || seconds < 0) return null;
+    return { version: 1, waitId, revision, remainingSeconds: seconds, ageMs: 0 };
+  }
+
+  /**
+   * Learn from the browser's presented-frame measurement for the current
+   * viewing. The saved source and link readings are the ones available at
+   * selection time, before the full track plan existed.
+   *
+   * @param {{ consumerId: string, generation: number, waitId: string, wait: number, elapsedMs: number }} params
+   * @returns {void}
+   */
+  noteFirstFrameObservation({ consumerId, generation, waitId, wait, elapsedMs }) {
+    const key = `${consumerId}:${waitId}`;
+    const early = this.#earlyWaits.get(key);
+    if (!early || early.generation !== generation || !Number.isSafeInteger(wait) || wait < 0 || early.observedWaits.has(wait) ||
+        !Number.isFinite(elapsedMs) || elapsedMs < 0) return;
+    for (const snapshot of early.snapshots) {
+      this.#host.noteFirstFrame?.({ seconds: elapsedMs / 1000, features: snapshot });
+    }
+    early.observedWaits.add(wait);
+    early.updatedAt = Date.now();
+  }
+
+  #setEarlyWait({ consumerId, generation, fileIndex, waitId, features, revision, current, sourceObserved = false }) {
+    const sameWait = current?.waitId === waitId;
+    const context = sameWait ? current : {
+      consumerId,
+      generation,
+      fileIndex,
+      waitId,
+      snapshots: [],
+      hasSourceObservation: false,
+      observedWaits: new Set()
+    };
+    Object.assign(context, { consumerId, generation, fileIndex, waitId, features, updatedAt: Date.now(), revision,
+      hasSourceObservation: context.hasSourceObservation || sourceObserved });
+    this.#earlyWaits.set(`${consumerId}:${waitId}`, context);
+    return context;
+  }
+
+  #recordEarlyWaitSnapshot(context, features) {
+    const previous = context.snapshots.at(-1);
+    if (previous && JSON.stringify(previous) === JSON.stringify(features)) return false;
+    const snapshot = { ...features };
+    if (context.snapshots.length < 2) context.snapshots.push(snapshot);
+    else context.snapshots[1] = snapshot;
+    return true;
+  }
+
+  #pruneEarlyWaits() {
+    const cutoff = Date.now() - 30 * 60_000;
+    for (const [key, value] of this.#earlyWaits) {
+      if (value.updatedAt < cutoff) this.#earlyWaits.delete(key);
+    }
+    while (this.#earlyWaits.size > 1000) this.#earlyWaits.delete(this.#earlyWaits.keys().next().value);
+  }
+
   /**
    * Open an output of a file for this viewer and put them on it.
    *

package/services/server/wire-outputs.js

@@ -650,6 +650,8 @@ export function wireOutputs({
       const predicted = Number(qualityStateOf(output).predictedSpeedWhenOffered);
       return Number.isFinite(predicted) && predicted > 0 ? predicted : null;
     },
+    firstFrameSecondsOf: (features) => parts.localObservations?.firstFrameSeconds(features) ?? null,
+    noteFirstFrame: (observation) => parts.localObservations?.noteFirstFrame(observation),
     audioDescriptionOf,
     openSecondsOf: (output) => runStartSecondsOf(output),
     processingStartupSecondsOf: (output) => runStartSecondsOf(output),

package/services/storage/files/CompletedFiles.js

@@ -24,8 +24,10 @@
  */
 
 import fs from "node:fs/promises";
+import { randomUUID } from "node:crypto";
 import os from "node:os";
 import path from "node:path";
+import { IDLE_KEEP_MS } from "../keep.js";
 
 /**
  * Where whole files live.
@@ -43,6 +45,17 @@ export function completedFilesRoot() {
 /** How a removal is asked for; Windows needs the retries, POSIX ignores them. */
 const REMOVAL = { force: true, maxRetries: 10, retryDelay: 20 };
 
+/** Whether another live process may still own an interrupted-write file. */
+function writerIsAlive(pid) {
+  if (!Number.isSafeInteger(pid) || pid < 1) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return error?.code === "EPERM";
+  }
+}
+
 /**
  * One directory of whole files, keyed by the torrent they came from.
  */
@@ -61,6 +74,11 @@ export class CompletedFiles {
   #readers = new Map();
   #removeAfterRead = new Set();
   #removing = new Set();
+  /** Last access time for idle expiry. @type {Map<string, number>} */
+  #lastUsedAt = new Map();
+  /** @type {() => number} */
+  #now;
+  #idleTtlMs;
 
   /**
    * What this store may hold, handed to it by the owner of the disk.
@@ -88,9 +106,13 @@ export class CompletedFiles {
    * @param {object} params
    * @param {string} params.root - Where whole files live. Outside any torrent's
    *   own store directory, which is removed with the torrent.
+   * @param {number} [params.idleTtlMs] - How long an unread file may remain.
+   * @param {() => number} [params.now]
    */
-  constructor({ root }) {
+  constructor({ root, idleTtlMs = IDLE_KEEP_MS, now = Date.now }) {
     this.#root = root;
+    this.#idleTtlMs = Math.max(0, Number(idleTtlMs) || 0);
+    this.#now = now;
   }
 
   /** Where these files live, for logging. */
@@ -148,21 +170,40 @@ export class CompletedFiles {
    * @returns {{ path: string, length: number, name: string } | null}
    */
   find(infoHash, fileIndex) {
+    const file = this.peek(infoHash, fileIndex);
+    if (file) this.#touch(this.#keyOf(infoHash, fileIndex));
+    return file;
+  }
+
+  /**
+   * Look up a file for bookkeeping without extending its idle period.
+   *
+   * @param {string} infoHash
+   * @param {number} fileIndex
+   * @returns {{ path: string, length: number, name: string } | null}
+   */
+  peek(infoHash, fileIndex) {
     const key = this.#keyOf(infoHash, fileIndex);
     if (this.#removeAfterRead.has(key) || this.#removing.has(key)) return null;
-    const file = this.#held.get(key) ?? null;
-    if (file) {
-      // WHEN IT WAS LAST WANTED, which is the order it leaves in. A whole file
-      // nobody has asked for in the longest is the one whose loss costs least:
-      // it can be downloaded again, and a read of it falls back to the pieces.
-      this.#touch(key);
-    }
-    return file;
+    return this.#held.get(key) ?? null;
   }
 
   /** Mark a file as more recently wanted than every earlier access. */
   #touch(key) {
     this.#lastRead.set(key, ++this.#accessOrder);
+    this.#lastUsedAt.set(key, this.#now());
+  }
+
+  /** Remove reusable whole files that have had no access for their idle period. */
+  async expireIdle(now = this.#now()) {
+    return this.#withAdmission(async () => {
+      let removed = 0;
+      for (const [key, lastUsedAt] of this.#lastUsedAt) {
+        if (now - lastUsedAt < this.#idleTtlMs || this.#readers.has(key) || this.#writing.has(key)) continue;
+        if (await this.#remove(key)) removed += 1;
+      }
+      return { bytes: this.bytes, removed };
+    });
   }
 
   /** Pin a completed file against eviction until all its offset reads finish. */
@@ -180,6 +221,7 @@ export class CompletedFiles {
       else {
         this.#readers.delete(key);
         if (this.#removeAfterRead.delete(key)) await this.#remove(key);
+        else this.#touch(key);
       }
       return this.allow(this.#allowanceBytes);
     } };
@@ -289,7 +331,10 @@ export class CompletedFiles {
     }
     this.#held.delete(key);
     this.#lastRead.delete(key);
+    this.#lastUsedAt.delete(key);
     this.#removing.delete(key);
+    const infoHash = key.slice(0, key.lastIndexOf("/"));
+    await this.#writeManifest(infoHash);
     return true;
   }
 
@@ -331,6 +376,23 @@ export class CompletedFiles {
         // a file named by its number is better than a file thrown away.
       }
       for (const held of files) {
+        const ownedPartial = held.isFile() && /^\d+\.partial-(\d+)-[0-9a-f-]+$/i.exec(held.name);
+        const legacyPartial = held.isFile() && /^\d+\.partial$/.test(held.name);
+        if (ownedPartial && !writerIsAlive(Number(ownedPartial[1]))) {
+          await fs.rm(path.join(this.#root, infoHash, held.name), REMOVAL).catch(() => undefined);
+          continue;
+        }
+        if (legacyPartial) {
+          const partial = path.join(this.#root, infoHash, held.name);
+          try {
+            const { mtimeMs } = await fs.stat(partial);
+            if (this.#now() - mtimeMs >= this.#idleTtlMs) await fs.rm(partial, REMOVAL);
+          } catch {
+            // Gone between listing and inspection, or still open on Windows.
+          }
+          continue;
+        }
+        if (ownedPartial) continue;
         const fileIndex = Number.parseInt(held.name, 10);
         if (!held.isFile() || !Number.isInteger(fileIndex) || fileIndex < 0) {
           continue;
@@ -348,11 +410,13 @@ export class CompletedFiles {
             length: size,
             name: String(manifest?.[String(fileIndex)]?.name ?? fileIndex)
           });
+          this.#touch(this.#keyOf(infoHash, fileIndex));
           adopted += 1;
         } catch {
           // Gone between the listing and the reading: not ours to worry about.
         }
       }
+      await this.#pruneTorrentDirectory(infoHash);
     }
     return adopted;
   }
@@ -407,12 +471,11 @@ export class CompletedFiles {
     }
     const directory = path.join(this.#root, String(infoHash));
     const where = path.join(directory, String(fileIndex));
-    const partial = `${where}.partial`;
+    const partial = `${where}.partial-${process.pid}-${randomUUID()}`;
     try {
       await fs.mkdir(directory, { recursive: true });
-      await fs.rm(partial, REMOVAL);
       const source = open();
-      const handle = await fs.open(partial, "w");
+      const handle = await fs.open(partial, "wx");
       let written = 0;
       try {
         for await (const chunk of source) {
@@ -440,8 +503,8 @@ export class CompletedFiles {
         this.#touch(key);
         this.#writing.delete(key);
         await this.#trimToAllowance();
+        await this.#writeManifest(infoHash);
       });
-      await this.#writeManifest(infoHash);
       return this.#held.get(key) ?? null;
     } catch {
       await fs.rm(partial, REMOVAL).catch(() => undefined);
@@ -451,6 +514,7 @@ export class CompletedFiles {
         this.#reservations.delete(key);
         this.#writing.delete(key);
         await this.#trimToAllowance();
+        await this.#pruneTorrentDirectory(infoHash);
       });
     }
   }
@@ -472,9 +536,24 @@ export class CompletedFiles {
         named[key.slice(infoHash.length + 1)] = { length: file.length, name: file.name };
       }
     }
-    await fs
-      .writeFile(path.join(this.#root, String(infoHash), "manifest.json"), JSON.stringify(named))
-      .catch(() => undefined);
+    const directory = path.join(this.#root, String(infoHash));
+    if (Object.keys(named).length === 0 && ![...this.#writing].some(key => key.startsWith(`${infoHash}/`))) {
+      await fs.rm(directory, { ...REMOVAL, recursive: true }).catch(() => undefined);
+      return;
+    }
+    await fs.writeFile(path.join(directory, "manifest.json"), JSON.stringify(named)).catch(() => undefined);
+  }
+
+  /** Remove an empty or partial-only directory discovered during startup. */
+  async #pruneTorrentDirectory(infoHash) {
+    if ([...this.#held.keys()].some(key => key.startsWith(`${infoHash}/`)) ||
+        [...this.#writing].some(key => key.startsWith(`${infoHash}/`))) return;
+    const directory = path.join(this.#root, String(infoHash));
+    let names = [];
+    try { names = await fs.readdir(directory); } catch { return; }
+    if (names.every(name => name === "manifest.json")) {
+      await fs.rm(directory, { ...REMOVAL, recursive: true }).catch(() => undefined);
+    }
   }
 
   /**
@@ -489,7 +568,8 @@ export class CompletedFiles {
         await this.#remove(key);
       }
     }
-    if (![...this.#held.keys()].some(key => key.startsWith(`${infoHash}/`))) {
+    if (![...this.#held.keys()].some(key => key.startsWith(`${infoHash}/`)) &&
+        ![...this.#writing].some(key => key.startsWith(`${infoHash}/`))) {
       await fs.rm(path.join(this.#root, String(infoHash)), { ...REMOVAL, recursive: true }).catch(() => undefined);
     }
   }

package/services/storage/keep.js

@@ -42,7 +42,7 @@
 /**
  * How long material nobody has read is kept, in milliseconds.
  *
- * Read by the torrent pool for a torrent and its downloaded bytes, and by the
- * session manager for the segments an encoder produced.
+ * Read by the torrent pool, the completed-file store, and the session manager
+ * for reusable torrents, source files, and generated segments.
  */
 export const IDLE_KEEP_MS = 60 * 60 * 1000;

package/services/torrent/worker/worker.js

@@ -1007,7 +1007,7 @@ const wholeSources = createWholeSources({ find: (infoHash, fileIndex) => complet
 /** Adopted files and newly completed files state the same availability event. */
 function announceWholeFiles(sourceKey, description) {
   for (const file of description?.files ?? []) {
-    const held = completedFiles.find(description.infoHash, file.index);
+    const held = completedFiles.peek(description.infoHash, file.index);
     if (!held || held.length !== file.length) continue;
     parentPort.postMessage({ type: Event.FILE_COMPLETE, sourceKey, infoHash: description.infoHash,
       fileIndex: file.index, path: held.path, length: held.length, name: file.name });
@@ -1085,6 +1085,9 @@ const beingKept = new Set();
  * @returns {Promise<void>}
  */
 async function keepWholeFiles() {
+  const expired = await completedFiles.expireIdle();
+  if (expired.removed > 0) holdingsChanged();
+
   for (const [sourceKey, torrent] of [...pool.torrents]) {
     // Lower case, because that is what the source key carries and the main
     // thread looks these up by the key alone.
@@ -1104,7 +1107,7 @@ async function keepWholeFiles() {
     const toKeep = filesToKeep({
       files: torrent.files,
       isKept: (fileIndex) =>
-        completedFiles.find(infoHash, fileIndex) !== null || beingKept.has(`${infoHash}/${fileIndex}`),
+        completedFiles.peek(infoHash, fileIndex) !== null || beingKept.has(`${infoHash}/${fileIndex}`),
       inUse: wanted
     });
     let announcedNow = false;
@@ -1169,7 +1172,7 @@ async function keepWholeFiles() {
     // above can take minutes and a read can open while it runs.
     const isRemovable = mayRemoveWholeTorrent({
       torrent,
-      isKept: (fileIndex) => completedFiles.find(infoHash, fileIndex) !== null,
+      isKept: (fileIndex) => completedFiles.peek(infoHash, fileIndex) !== null,
       openReads: openReads.values(),
       announcedNow
     });