@torrent-tv/proxy 2.96.14 → 2.97.1

package/services/encode/EncodeRuns.js

@@ -20,6 +20,7 @@ import { writeAdmittedInput } from "./AdmittedInput.js";
 import { cutOf, cutShiftOf, judgeNeighbors, judgePiece } from "./piece-completeness.js";
 import { presentationSegment } from "./segment-formats/presentation-segment.js";
 import { InputFailures, failedAdmittedInput } from "./InputFailures.js";
+import { readProcessCpuSeconds } from "./host-load.js";
 
 
 /**
@@ -161,6 +162,15 @@ export class EncodeRuns {
    * @type {Map<number, import("./EncodeRun.js").EncodeRun>}
    */
   #runsByInputToken = new Map();
+  /**
+   * Each live run's ffmpeg CPU seconds against the film it had made, as of its
+   * last progress report: what one second of film costs this machine in
+   * processor time, which the speed in x does not say once other work shares
+   * the processor (torrent-tv/meta#177). Said when the run ends.
+   *
+   * @type {WeakMap<object, { cpuSeconds: number, filmSeconds: number, reading: boolean, beside: number }>}
+   */
+  #cpuOfRun = new WeakMap();
 
   #lastInputToken = 0;
   #inputFailures = new InputFailures();
@@ -572,6 +582,7 @@ export class EncodeRuns {
     this.#host.encodeInputs?.forget(output);
     if (this.#host.outputs.outputsOn(output.outputKey).length === 0) {
       this.#inputFailures.forget(output.outputKey);
+      this.#host.encodeOrchestrator.forgetOpens?.(output.outputKey);
       this.#host.encodeOrchestrator.forgetOutput(output.outputKey);
     }
   }
@@ -783,40 +794,6 @@ export class EncodeRuns {
     );
   }
 
-  /**
-   * How far a run starting here may work before it meets somebody else's
-   * material — read off the ONE coverage map, never worked out again here.
-   *
-   * This replaced `planRunInterval`, which was a second authority over the same
-   * question and answered it by different rules: it walked the whole track for
-   * the first free number, MOVED the start there itself, and counted every live
-   * run as claiming up to `head + look-ahead`. Measured in the field
-   * 2026-09-05: the plan commanded a start at #46, this moved it to #78 — the
-   * "run moved forward from #46 to #78" line — and the plan, seeing a run
-   * outside the window it had asked for, killed it as unwanted and commanded
-   * the same start again, 350-700ms per cycle, dozens of times, the viewer's
-   * picture stopped for 125 seconds.
-   *
-   * Where a run STARTS is the plan's decision and arrives here as an argument.
-   * All this answers is where it must stop, and the answer is a fact of the
-   * map: the free stretch from that number on. `-1` means the end of the track,
-   * which is what "no end" is written as everywhere here.
-   *
-   * @param {object} session
-   * @param {number} startIndex
-   * @param {object | null} exceptRun - The run being replaced, whose own claim
-   *   is not somebody else's material.
-   * @returns {number} The last number to work through, or `-1` for the end.
-   */
-  #runEndFrom(session, startIndex, exceptRun = null) {
-    return this.#host.encodeOrchestrator.freeStretchEnd({
-      address: session.outputKey ?? "",
-      from: startIndex,
-      exceptRun,
-      segmentCount: Number(session.timeline?.segmentCount) || 0
-    });
-  }
-
   // Returns the encoder it built, or nothing when there was nothing to build.
   // It waits for nothing: the one thing it used to wait for was the death of
   // the run it was replacing, and that killing is gone.
@@ -824,7 +801,10 @@ export class EncodeRuns {
     if (!this.isLive(session)) {
       return null;
     }
-    this.#host.encodeInputs?.retain(session, this.#host.encodeOrchestrator.wantedSegmentsOn(session.outputKey));
+    // A copy held for a start that no live run ends before and that is not
+    // being started now goes back (torrent-tv/meta#184).
+    this.#host.encodeInputs?.retain(session, this.#host.encodeOrchestrator.wantedSegmentsOn(session.outputKey),
+      new Set([startIndex, ...this.liveRunsOf(session).map((run) => run.to + 1)]));
     // THE LAST NUMBER THIS RUN MAY REACH is the plan's; how far its input
     // really reaches is the input's answer. An original input is one copied
     // stretch, and the run is given exactly that stretch (torrent-tv/meta#158).
@@ -837,13 +817,13 @@ export class EncodeRuns {
     // The stretch is part of an original input's identity: two stretches from
     // one start can hold the same padded bytes, and a stretch that failed is
     // refused only while it is the same stretch.
-    const inputParameters = admittedInput ? { outputKey: session.outputKey, encoder: this.#host.videoEncoder.name,
+    const inputParameters = { outputKey: session.outputKey, encoder: this.#host.videoEncoder.name,
       width: session.output.encodeWidth, height: session.output.encodeHeight, fps: session.output.outputFps,
       preset: session.output.softwarePreset, tonemap: session.output.applyTonemap,
       rateControl: session.spec.video?.encode?.rateControl ?? null,
-      ...(admittedInput.original ? { interval: [startIndex, inputEnd] } : {}) } : null;
-    const inputKey = admittedInput ? this.#inputFailures.key(admittedInput, inputParameters) : null;
-    if (inputKey && this.#inputFailures.failure(session.outputKey, startIndex, inputKey)) {
+      ...(admittedInput.original ? { interval: [startIndex, inputEnd] } : {}) };
+    const inputKey = this.#inputFailures.key(admittedInput, inputParameters);
+    if (this.#inputFailures.failure(session.outputKey, startIndex, inputKey)) {
       admittedInput.release();
       return null;
     }
@@ -869,9 +849,10 @@ export class EncodeRuns {
     // an argument. Reading it off the coverage map a second time was the last
     // remaining second answer to that question: the plan computed `to`, passed
     // it, and the parameter list did not name it.
-    const runEnd = admittedInput ? inputEnd : Number.isInteger(ordered?.to)
-      ? ordered.to
-      : this.#runEndFrom(session, startIndex, null);
+    // A run ends where its input does: an original input is one copied
+    // stretch, and a packet input grows one segment at a time from its first
+    // (`run.to` follows it below).
+    const runEnd = inputEnd;
     // The restart backs off a segment or two from what was asked for, so the
     // request that prompted it is recorded under a HIGHER index than the run
     // starts at. Looking it up by the start index alone found nothing and the
@@ -1046,11 +1027,12 @@ export class EncodeRuns {
             const since = (at) => at ? `${at - run.startedAt}ms` : "never";
             this.#host.logger.info(`encode input of run #${run.from}..#${run.to} on ${session.outputKey}: ` +
               `${reads.count} read(s), ${reads.bytes} bytes, first at ${since(reads.firstAt)}, last at ${since(reads.lastAt)}, ` +
-              `ended at ${Date.now() - run.startedAt}ms`);
+              `ended at ${Date.now() - run.startedAt}ms` + describeTaken(reads.answers, run.startedAt, ended.firstNamedWallMs));
           }
           this.#noteOpen(session, run, ended);
           admittedInput.release();
         }
+        this.#sayRunCpu(session, run);
         this.noteRunEnded(session, run, ended);
         this.#host.encodersChanged?.();
       }
@@ -1061,10 +1043,6 @@ export class EncodeRuns {
       // Every number of the stretch answers to its one key, so a failure
       // anywhere inside it is recorded against the stretch that was commanded.
       run.admittedInputKeys = new Map(Array.from({ length: inputEnd - safeIndex + 1 }, (_, offset) => [safeIndex + offset, inputKey]));
-      // What this run can make is what its input holds, and that is what it
-      // claims; the plan's longer bound would read as made by a run that
-      // cannot reach it.
-      run.inputThrough = inputEnd;
       run.process.stdin.end();
       // THE NEXT STRETCH IS PREPARED WHILE THIS ONE IS BEING MADE. Asked for
       // only when this run had ended, its copy fell between the two runs and
@@ -1148,7 +1126,7 @@ export class EncodeRuns {
     const speed = run.speedX > 0 ? run.speedX : this.#host.encodeOrchestrator.speedOn?.(session.outputKey) ?? 0;
     if (!Number.isFinite(ended.firstNamedMs) || !(pieceSeconds > 0) || !(speed > 0)) return;
     const openSeconds = Math.max(0, ended.firstNamedMs / 1000 - pieceSeconds / speed);
-    this.#host.encodeInputs?.noteOpen(session, openSeconds);
+    this.#host.encodeOrchestrator.noteOpen?.(session.outputKey ?? "", openSeconds);
     this.#host.logger.info(`encode input of run #${run.from}..#${run.to} on ${session.outputKey}: opened in ` +
       `${openSeconds.toFixed(2)}s (first piece named at ${ended.firstNamedMs}ms, ${pieceSeconds.toFixed(3)}s of film at ${speed.toFixed(2)}x)`);
   }
@@ -1167,6 +1145,7 @@ export class EncodeRuns {
     if (!this.isLive(session) || !this.runsOf(session).includes(run)) {
       return;
     }
+    this.#readRunCpu(run, progress);
     if (run.progress.shouldLog(PROGRESS_LOG_INTERVAL_MS)) {
       this.#host.logger.info(
         `transcode ${session.id} "${session.file.name}" ${progress.percent.toFixed(1)}% ` +
@@ -1176,6 +1155,44 @@ export class EncodeRuns {
     }
   }
 
+  /**
+   * Read the run's ffmpeg CPU beside the film it has made, one reading at a
+   * time; a reading that cannot be taken (no `/proc`, the process gone)
+   * leaves the last one.
+   *
+   * @param {import("./EncodeRun.js").EncodeRun} run
+   * @param {{ processedSeconds?: number, startPositionSeconds?: number }} progress
+   */
+  #readRunCpu(run, progress) {
+    const pid = run.process?.pid;
+    const filmSeconds = Number(progress?.processedSeconds) - Number(progress?.startPositionSeconds ?? 0);
+    const known = this.#cpuOfRun.get(run) ?? { cpuSeconds: 0, filmSeconds: 0, reading: false, beside: 0 };
+    this.#cpuOfRun.set(run, known);
+    if (known.reading || !Number.isInteger(pid) || !(filmSeconds > 0)) return;
+    known.reading = true;
+    void readProcessCpuSeconds(pid).then((cpuSeconds) => {
+      if (Number.isFinite(cpuSeconds)) {
+        known.cpuSeconds = cpuSeconds;
+        known.filmSeconds = filmSeconds;
+        known.beside = Math.max(known.beside, this.#runsByInputToken.size - 1);
+      }
+    }).finally(() => { known.reading = false; });
+  }
+
+  /**
+   * What the run's ffmpeg spent per second of film, said once when it ends.
+   *
+   * @param {object} session
+   * @param {import("./EncodeRun.js").EncodeRun} run
+   */
+  #sayRunCpu(session, run) {
+    const known = this.#cpuOfRun.get(run);
+    if (!known || !(known.filmSeconds > 0) || !(known.cpuSeconds > 0)) return;
+    this.#host.logger.info(`encode-run #${run.from}..#${run.to} on ${session.outputKey}: ffmpeg used ` +
+      `${known.cpuSeconds.toFixed(2)}s of CPU for ${known.filmSeconds.toFixed(2)}s of film, ` +
+      `${(known.cpuSeconds / known.filmSeconds).toFixed(3)}s per second of film; at most ${known.beside} other encoder(s) alive beside it`);
+  }
+
   /**
    * What to do about a run that has ended.
    *
@@ -1531,3 +1548,26 @@ export class EncodeRuns {
     });
   }
 }
+
+/**
+ * What FFmpeg was handed of an original input, as a clause of the run's input
+ * line (torrent-tv/meta#177): bytes handed to the system (at most what it
+ * read), connections closed before an answer was all handed over,
+ * the share of reads that went forward, the largest jump back, bytes taken
+ * twice, and what it read before it named its first piece — its open.
+ *
+ * @param {{ count: number, written: number, unfinished: number, forwardShare: number | null, largestBackBytes: number, rewritten: number, list: { at: number, written: number }[] } | undefined} answers
+ * @param {number} startedAt
+ * @param {number | null | undefined} firstNamedMs
+ * @returns {string}
+ */
+function describeTaken(answers, startedAt, firstNamedMs) {
+  if (!answers || answers.count === 0) return "";
+  const opened = Number.isFinite(firstNamedMs)
+    ? answers.list.filter((answer) => answer.at - startedAt <= firstNamedMs) : null;
+  return `; handed over: ${answers.written} bytes in ${answers.count} answer(s), ${answers.unfinished} closed before all was handed over, ` +
+    `${answers.forwardShare === null ? "n/a" : `${Math.round(answers.forwardShare * 100)}%`} forward, ` +
+    `largest jump back ${answers.largestBackBytes} bytes, ${answers.rewritten} bytes taken twice` +
+    (opened ? `; before the first piece was named ${opened.length} answer(s), ` +
+      `${opened.reduce((sum, answer) => sum + answer.written, 0)} bytes` : "");
+}

package/services/encode/OriginalInput.js

@@ -35,6 +35,11 @@ export async function admitOriginalInput({ sources, reserve, readRanges, now = D
     // time went: field 2026-10-08, a run took 6-9 s for a piece FFmpeg makes in
     // 1.6 s from a file, and nothing said whether it was waiting on its input.
     const reads = { count: 0, bytes: 0, firstAt: 0, lastAt: 0 };
+    // Each answer FFmpeg was sent, in order: where it began, where its range
+    // ended, what was handed to the system before the connection closed, and
+    // whether all of it was (torrent-tv/meta#177).
+    /** @type {{ fileIndex: number, start: number, end: number, written: number, handedOver: boolean, at: number }[]} */
+    const answers = [];
     return {
       kind: "result", original: true, sources, bytes, copyMs, fingerprint: hash.digest("hex"),
       // No track's own end: the container names the bytes an interval needs,
@@ -59,7 +64,10 @@ export async function admitOriginalInput({ sources, reserve, readRanges, now = D
         return { length: fileLength, end: stop, bytes: entry.buffers[position].subarray(start - ranges[position][0], stop - ranges[position][0] + 1) };
       },
       lengthOf: fileIndex => held.get(fileIndex)?.source.input.fileLength ?? null,
-      reads: () => ({ ...reads }),
+      reads: () => ({ ...reads, answers: describeAnswers(answers) }),
+      noteAnswer(answer) {
+        if (!released) answers.push({ ...answer, at: Date.now() });
+      },
       release() {
         if (released) return;
         released = true;
@@ -77,3 +85,39 @@ export function originalInputBytes(sources) {
   return sources.reduce((total, source) => total + source.input.ranges
     .reduce((sum, [start, end]) => sum + end - start + 1, 0), 0);
 }
+
+/**
+ * The shape of FFmpeg's reads of one input, from the answers it was sent:
+ * how much was handed to the system (at most what FFmpeg read), how many
+ * connections closed before all of an answer was handed over, what share began
+ * at or after the end of the previous one (a forward read), the largest jump
+ * back, and the bytes written again that an earlier answer had already
+ * written. Per file, since two files are read independently.
+ *
+ * @param {{ fileIndex: number, start: number, end: number, written: number, handedOver: boolean, at: number }[]} answers
+ * @returns {{ count: number, written: number, unfinished: number, forwardShare: number | null, largestBackBytes: number, rewritten: number, list: object[] }}
+ */
+export function describeAnswers(answers) {
+  let written = 0, unfinished = 0, forward = 0, largestBackBytes = 0, rewritten = 0;
+  const reachedOf = new Map();
+  const coveredOf = new Map();
+  for (const answer of answers) {
+    written += answer.written;
+    if (!answer.handedOver) unfinished += 1;
+    const reached = reachedOf.get(answer.fileIndex);
+    if (reached === undefined || answer.start >= reached) forward += 1;
+    else largestBackBytes = Math.max(largestBackBytes, reached - answer.start);
+    // Bytes actually taken by this answer, as a range from its start.
+    const takenEnd = answer.start + Math.max(0, answer.written) - 1;
+    const covered = coveredOf.get(answer.fileIndex) ?? [];
+    for (const [from, to] of covered) {
+      const overlap = Math.min(to, takenEnd) - Math.max(from, answer.start) + 1;
+      if (overlap > 0) rewritten += overlap;
+    }
+    if (takenEnd >= answer.start) covered.push([answer.start, takenEnd]);
+    coveredOf.set(answer.fileIndex, covered);
+    reachedOf.set(answer.fileIndex, Math.max(reached ?? 0, takenEnd + 1));
+  }
+  return { count: answers.length, written, unfinished,
+    forwardShare: answers.length ? forward / answers.length : null, largestBackBytes, rewritten, list: answers };
+}

package/services/encode/RunClock.js

@@ -28,6 +28,15 @@ export class RunClock {
   #idleCauses = 0;
   #idleSince = 0;
   #idleMs = 0;
+  /**
+   * Stopped time alone, apart from input waits: a pause is a decision of
+   * ours, while a wait for input is part of what starting a run costs, so the
+   * readings of a start leave out the first and keep the second
+   * (torrent-tv/meta#184).
+   */
+  #stoppedSince = 0;
+  #stoppedMs = 0;
+  #isStopped = false;
 
   /**
    * @param {{ now?: () => number }} [options]
@@ -67,11 +76,29 @@ export class RunClock {
   /** The process is stopped. */
   stopped() {
     this.#idleBegins();
+    if (!this.#isStopped) {
+      this.#isStopped = true;
+      this.#stoppedSince = this.#now();
+    }
   }
 
   /** The process runs again. */
   continued() {
     this.#idleEnds();
+    if (this.#isStopped) {
+      this.#isStopped = false;
+      this.#stoppedMs += this.#now() - this.#stoppedSince;
+    }
+  }
+
+  /**
+   * Milliseconds the process has been stopped so far.
+   *
+   * @param {number} [at]
+   * @returns {number}
+   */
+  stoppedMs(at = this.#now()) {
+    return this.#stoppedMs + (this.#isStopped ? Math.max(0, at - this.#stoppedSince) : 0);
   }
 
   /**

package/services/encode/run-costs.js

@@ -100,8 +100,10 @@ export class RunCosts {
     // Without it the figure that prices a move could only ever be learned from
     // runs that survived, so the state in which moves are ruinous was exactly
     // the state in which their cost stayed unknown.
-    if (!Number.isFinite(ended?.firstOutputMs) && Number.isFinite(ended?.livedMs) && ended.livedMs > 0) {
-      RunCosts.#keep(this.#firstOutput, /** @type {number} */ (ended.livedMs));
+    // Its pauses are left out: a pause is our decision, not what a start costs.
+    const livedWorking = Number(ended?.livedMs) - Math.max(0, Number(ended?.stoppedMs) || 0);
+    if (!Number.isFinite(ended?.firstOutputMs) && Number.isFinite(livedWorking) && livedWorking > 0) {
+      RunCosts.#keep(this.#firstOutput, livedWorking);
     }
     if (Number.isFinite(ended?.dyingMs)) {
       RunCosts.#keep(this.#dying, /** @type {number} */ (ended.dyingMs));
@@ -111,6 +113,49 @@ export class RunCosts {
     }
   }
 
+  /**
+   * How long an encoder took to open one output's original input, in seconds:
+   * from its spawn to the name of its first closed piece, less that piece's
+   * encoding and any pause (torrent-tv/meta#184). Kept per output, beside the
+   * host's time to first output above and apart from it: the two are related
+   * and not the same quantity, and the stretch of an original input is sized
+   * from this one.
+   *
+   * @type {Map<string, number[]>}
+   */
+  #opens = new Map();
+
+  /**
+   * @param {string} address
+   * @param {number} seconds
+   */
+  noteOpen(address, seconds) {
+    if (!address || !Number.isFinite(seconds) || seconds < 0) return;
+    const readings = this.#opens.get(address) ?? [];
+    RunCosts.#keep(readings, seconds);
+    this.#opens.set(address, readings);
+  }
+
+  /**
+   * The open of this output: its own readings' median where it has any; else
+   * the host's startup reading of spawn to first piece, said to be an
+   * approximation — it opened a generated picture, not this file; else null.
+   *
+   * @param {string} address
+   * @returns {{ seconds: number, measured: boolean } | null}
+   */
+  openOf(address) {
+    const own = middleOf(this.#opens.get(address) ?? []);
+    if (own !== null) return { seconds: own, measured: true };
+    const startup = this.#atStartup?.firstByteWaitSec;
+    return Number.isFinite(startup) && startup > 0 ? { seconds: startup, measured: false } : null;
+  }
+
+  /** @param {string} address */
+  forgetOpens(address) {
+    this.#opens.delete(address);
+  }
+
   /**
    * @param {number[]} readings
    * @param {number} value

package/services/server/wire-outputs.js

@@ -975,6 +975,9 @@ export function wireOutputs({
     heldRanges: readEncodeHeldRanges,
     reviseBudget: () => parts.machineBudget.revise(),
     capacity: () => parts.machineBudget.capacityOf("memory"),
+    // How long this output's input takes to open, from the one owner of start
+    // readings (torrent-tv/meta#184).
+    openOf: (output) => parts.encodeOrchestrator?.openOf?.(output.outputKey ?? "") ?? null,
     urgent: (output, index) => parts.encodeOrchestrator.wantedSegmentsOn(output.outputKey).some(window =>
       index >= window.from && index <= window.to && window.urgent === true),
     log: line => logger.info(line),

package/services/storage/MachineBudget.js

@@ -77,6 +77,13 @@ import { OtherDemand, divideAllowance } from "./allowance.js";
 export class MachineBudget {
   #revisionPromise = null;
   #reviseAgain = false;
+  /**
+   * The revision in hand, for its own line: when it was first asked for, how
+   * many asks joined it, and which pass this is. At a cold start on the addon
+   * host a caller waited 20.2 s inside `revise()` and nothing said whether it
+   * waited for passes, for a reading, or for the thread (torrent-tv/meta#177).
+   */
+  #revision = null;
   /** Resource name → how to read what is free, and what others have needed. */
   #resources = new Map();
 
@@ -151,11 +158,14 @@ export class MachineBudget {
   revise() {
     if (this.#revisionPromise) {
       this.#reviseAgain = true;
+      this.#revision.asks += 1;
       return this.#revisionPromise;
     }
+    this.#revision = { askedAt: Date.now(), asks: 1, pass: 0 };
     this.#revisionPromise = (async () => {
       do {
         this.#reviseAgain = false;
+        this.#revision.pass += 1;
         await this.#readRevision();
       } while (this.#reviseAgain);
       return this.#last;
@@ -164,13 +174,17 @@ export class MachineBudget {
   }
 
   async #readRevision() {
+    const passFrom = Date.now();
+    let readingMs = 0;
     for (const [name, resource] of this.#resources) {
       const claimants = this.#claimants.filter((one) => one.resource === name);
       if (claimants.length === 0) {
         continue;
       }
       const held = claimants.reduce((sum, one) => sum + Math.max(0, one.held()), 0);
+      const readFrom = Date.now();
       const free = await resource.readFree();
+      readingMs += Date.now() - readFrom;
       // WITHOUT A READING, NOTHING IS ALLOWED TO GROW. A resource whose free
       // space cannot be read is not a resource with room; answering "unbounded"
       // there is how the spill file came to have no limit in the first place.
@@ -197,7 +211,11 @@ export class MachineBudget {
         );
       }
     }
-    this.#logger?.info?.(this.describe());
+    const revision = this.#revision;
+    this.#logger?.info?.(`${this.describe()}` + (revision
+      ? ` (pass ${revision.pass} of a revision asked ${revision.asks} time(s), first ${Date.now() - revision.askedAt}ms ago; ` +
+        `this pass ${Date.now() - passFrom}ms, ${readingMs}ms of it reading what is free)`
+      : ""));
     return this.#last;
   }
 

package/services/storage/cpu-profile.js

@@ -0,0 +1,68 @@
+/**
+ * @file A CPU profile of the main thread at a cold start, asked for by the
+ * operator and never taken otherwise (torrent-tv/meta#177).
+ *
+ * At a cold start on the addon host (#166 run 12) the picture's first input
+ * waited 29.5 s, 20.2 s of it inside a budget revision, while the main thread
+ * ran at 83-108 % of a core; what it was doing is not in any log. A profile of
+ * that thread names it.
+ *
+ * In-process, through `node:inspector`: the sampling profiler runs beside the
+ * thread and does not stop it — unlike the debugger that stopped every thread
+ * of this process on 2026-09-05 (torrent-tv/meta#77). It begins at the first
+ * source opened, which is where a cold start begins, runs for the seconds the
+ * operator named, and writes `cpu-start-<time>.cpuprofile` beside the log,
+ * readable in Chrome's DevTools (Performance, "Load profile").
+ */
+
+import { Session } from "node:inspector/promises";
+import { writeFile } from "node:fs/promises";
+import path from "node:path";
+
+/**
+ * @param {object} params
+ * @param {number} params.seconds - How long to profile; nothing happens unless positive.
+ * @param {string} params.dir - Where to write the profile.
+ * @param {(line: string) => void} params.log
+ * @param {(bytes: number) => boolean} [params.mayKeep] - Whether the storage budget lets it be kept.
+ * @returns {{ begin: () => void, active: () => boolean }}
+ */
+export function startupCpuProfile({ seconds, dir, log, mayKeep = () => true }) {
+  let begun = false;
+  let running = false;
+  const wanted = Number.isFinite(seconds) && seconds > 0 && typeof dir === "string" && dir.length > 0;
+  const take = async () => {
+    const session = new Session();
+    session.connect();
+    try {
+      await session.post("Profiler.enable");
+      await session.post("Profiler.start");
+      running = true;
+      log(`cpu profile: the main thread is profiled for ${seconds}s from the first source opened`);
+      await new Promise((resolve) => {
+        const timer = setTimeout(resolve, seconds * 1000);
+        if (typeof timer.unref === "function") timer.unref();
+      });
+      const { profile } = await session.post("Profiler.stop");
+      const text = JSON.stringify(profile);
+      if (!mayKeep(Buffer.byteLength(text))) {
+        log(`cpu profile: not kept, ${Buffer.byteLength(text)} bytes refused by the storage budget`);
+        return;
+      }
+      const file = path.join(dir, `cpu-start-${new Date().toISOString().replace(/[:.]/g, "-")}.cpuprofile`);
+      await writeFile(file, text);
+      log(`cpu profile: written to ${file} (${Buffer.byteLength(text)} bytes)`);
+    } finally {
+      running = false;
+      session.disconnect();
+    }
+  };
+  return {
+    begin() {
+      if (!wanted || begun) return;
+      begun = true;
+      void take().catch((error) => log(`cpu profile: failed — ${error.message}`));
+    },
+    active: () => running
+  };
+}