@hyperframes/engine 0.8.207 → 0.8.209

package/dist/index.d.ts

@@ -73,8 +73,8 @@ export { aacSegmentCount, encodeAac } from "./services/aacEncode.js";
 export { ManagedChildProcess, type ManagedChildProcessOptions, type ManagedChildProcessOutcome, type ManagedProcessTerminationReason, } from "./utils/managedChildProcess.js";
 export { assertConfiguredFfmpegBinariesExist, getFfmpegBinary, getFfprobeBinary, FFMPEG_PATH_ENV, FFPROBE_PATH_ENV, } from "./utils/ffmpegBinaries.js";
 export { trackChildProcess, killTrackedProcesses } from "./utils/processTracker.js";
-export { renameWithRetry, renameWithRetryAsync } from "./utils/renameWithRetry.js";
-export { removeScratch, collectScratchLeftovers } from "./utils/removeScratch.js";
+export { renameWithRetry, renameWithRetryAsync } from "@hyperframes/core/rename-retry";
+export { removeScratch, collectScratchLeftovers } from "@hyperframes/core/remove-scratch";
 export { psnrDb, resolveDeVerifyMinDb } from "./utils/psnr.js";
 export { decodePng, decodePngToRgb48le, blitRgba8OverRgb48le, blitRgb48leRegion, blitRgb48leAffine, parseTransformMatrix, roundedRectAlpha, resampleRgb48leObjectFit, normalizeObjectFit, type ObjectFit, } from "./utils/alphaBlit.js";
 export { groupIntoLayers, type CompositeLayer } from "./utils/layerCompositor.js";
@@ -87,3 +87,4 @@ export { isHdrColorSpace, detectTransfer, getHdrEncoderColorParams, analyzeCompo
 export type { VideoColorSpace } from "./utils/ffprobe.js";
 export { renderProvenanceArgs, appendRenderProvenanceArgs, readRenderProvenance, PROVENANCE_RENDERER_TAG, PROVENANCE_VERSION_TAG, PROVENANCE_RENDERER_NAME, PROVENANCE_VERSION, type RenderProvenance, } from "./utils/renderProvenance.js";
 export { DrawElementCaptureError, isDrawElementCaptureError, } from "./services/drawElementCaptureError.js";
+export { inAgentSandbox, isOneProcessOverPipe, machServiceDenied, oneProcessOverPipe, pipeLaunchClosedOnMac, sandboxDeniedRemediation, } from "./services/sandboxLaunch.js";

package/dist/index.js

@@ -77,8 +77,8 @@ export { aacSegmentCount, encodeAac } from "./services/aacEncode.js";
 export { ManagedChildProcess, } from "./utils/managedChildProcess.js";
 export { assertConfiguredFfmpegBinariesExist, getFfmpegBinary, getFfprobeBinary, FFMPEG_PATH_ENV, FFPROBE_PATH_ENV, } from "./utils/ffmpegBinaries.js";
 export { trackChildProcess, killTrackedProcesses } from "./utils/processTracker.js";
-export { renameWithRetry, renameWithRetryAsync } from "./utils/renameWithRetry.js";
-export { removeScratch, collectScratchLeftovers } from "./utils/removeScratch.js";
+export { renameWithRetry, renameWithRetryAsync } from "@hyperframes/core/rename-retry";
+export { removeScratch, collectScratchLeftovers } from "@hyperframes/core/remove-scratch";
 // drawElement self-verify comparison — shared by the streaming drain
 // (producer) and the parallel disk-path verify (parallelCoordinator).
 export { psnrDb, resolveDeVerifyMinDb } from "./utils/psnr.js";
@@ -93,3 +93,4 @@ export { hideVideoElements, showVideoElements, queryVideoElementBounds, queryEle
 export { isHdrColorSpace, detectTransfer, getHdrEncoderColorParams, analyzeCompositionHdr, findHdrAutoPromotion, formatHdrAutoPromotionWarning, sanitizeHdrAutoPromotionAsset, DEFAULT_HDR10_MASTERING, HDR_AUTO_PROMOTION_PIPELINE, } from "./utils/hdr.js";
 export { renderProvenanceArgs, appendRenderProvenanceArgs, readRenderProvenance, PROVENANCE_RENDERER_TAG, PROVENANCE_VERSION_TAG, PROVENANCE_RENDERER_NAME, PROVENANCE_VERSION, } from "./utils/renderProvenance.js";
 export { DrawElementCaptureError, isDrawElementCaptureError, } from "./services/drawElementCaptureError.js";
+export { inAgentSandbox, isOneProcessOverPipe, machServiceDenied, oneProcessOverPipe, pipeLaunchClosedOnMac, sandboxDeniedRemediation, } from "./services/sandboxLaunch.js";

package/dist/services/aacEncode.js

@@ -4,7 +4,7 @@
  */
 import { execFile } from "node:child_process";
 import { mkdtempSync, readFileSync, writeFileSync } from "node:fs";
-import { removeScratch } from "../utils/removeScratch.js";
+import { removeScratch } from "@hyperframes/core/remove-scratch";
 import { dirname, join } from "node:path";
 import { getFfmpegBinary } from "../utils/ffmpegBinaries.js";
 import { runFfmpeg } from "../utils/runFfmpeg.js";

package/dist/services/audioFxRender.js

@@ -18,8 +18,8 @@ import { pathToFileURL } from "node:url";
 import { getAudioFxRuntimeScript } from "@hyperframes/core/audio-fx-runtime";
 import { enabledAudioFxNodes } from "@hyperframes/core/audio-fx";
 import { serializeAutomation } from "@hyperframes/core/audio-automation";
-import { removeScratch } from "../utils/removeScratch.js";
-import { acquireBrowser } from "./browserManager.js";
+import { removeScratch } from "@hyperframes/core/remove-scratch";
+import { acquireBrowser, buildChromeArgs } from "./browserManager.js";
 import { createEnvelopeWalker } from "./audioVolumeEnvelope.js";
 import { riffChunks, wavFormatTag } from "./wavChunks.js";
 import { windowPrerollSeconds } from "./audioFxWarmup.js";
@@ -439,6 +439,9 @@ export async function applyAudioFxChain(inputWav, chain, outputWav, options) {
         }
     });
 }
+/** Audio processing needs no GPU, so software mode; every other launch detail is the shared one. */
+let fxBrowserArgs;
+const fxChromeArgs = () => (fxBrowserArgs ??= buildChromeArgs({ width: 1280, height: 720, captureMode: "screenshot" }, { browserGpuMode: "software" }));
 /** Run `body` with a leased browser and a way to open pages on the runtime; both are released in the same try that takes them. */
 async function withFxBrowser(options, body) {
     const hostDir = mkdtempSync(join(tmpdir(), "hf-fx-host-"));
@@ -451,7 +454,7 @@ async function withFxBrowser(options, body) {
         if (options.signal?.aborted) {
             throw new AudioFxRenderError(`Audio FX cancelled for track ${options.trackId}`);
         }
-        lease = await acquireBrowser(["--no-sandbox", "--autoplay-policy=no-user-gesture-required"]);
+        lease = await acquireBrowser(fxChromeArgs());
         const { browser } = lease;
         return await body(() => openFxPage(browser, hostDir));
     }

package/dist/services/audioMixer.js

@@ -1,8 +1,8 @@
 // fallow-ignore-file complexity code-duplication
 import { isSelfOrAncestorHidden, memberGroupKey, isMemberGroupHidden } from "./mediaHidden.js";
 import { closeSync, existsSync, mkdirSync, mkdtempSync, openSync, rmSync, writeFileSync } from "fs";
-import { renameWithRetry } from "../utils/renameWithRetry.js";
-import { removeScratch } from "../utils/removeScratch.js";
+import { renameWithRetry } from "@hyperframes/core/rename-retry";
+import { removeScratch } from "@hyperframes/core/remove-scratch";
 import { join, dirname, isAbsolute, relative } from "path";
 import { parseHTML } from "linkedom";
 import { extractAudioMetadata } from "../utils/ffprobe.js";
@@ -78,11 +78,11 @@ function buildAtempoFilter(playbackRate) {
 const RAMP_SLICE_SECONDS = 0.25;
 const MAX_RAMP_SLICES = 240;
 /** Bake a rate lane as consecutive source slices, each stretched by its mean `sourceTimeAt` rate, keeping pitch. */
-function buildRampFilterComplex(lane, duration, headFilter, tailFilter) {
+function buildRampFilterComplex(lane, duration, headFilter, tailFilter, input) {
     const slices = Math.min(MAX_RAMP_SLICES, Math.max(1, Math.ceil(duration / RAMP_SLICE_SECONDS)));
     const step = duration / slices;
     const split = Array.from({ length: slices }, (_, i) => `[s${i}]`).join("");
-    const parts = [`[0:a]${headFilter ? `${headFilter},` : ""}asplit=${slices}${split}`];
+    const parts = [`[${input}]${headFilter ? `${headFilter},` : ""}asplit=${slices}${split}`];
     for (let i = 0; i < slices; i += 1) {
         const from = sourceTimeAt(lane, i * step);
         const to = sourceTimeAt(lane, (i + 1) * step);
@@ -103,17 +103,17 @@ function buildRampFilterComplex(lane, duration, headFilter, tailFilter) {
         parts.push(`[cat]${tailFilter}[out]`);
     return parts.join(";");
 }
-function preparedAudioOutputArgs(metadata, playbackRate, duration, headFilter) {
+function preparedAudioOutputArgs(metadata, playbackRate, duration, headFilter, stream) {
     const channelFilter = metadata?.channels === 1 ? STEREO_CHANNEL_FILTER : null;
     const outputArgs = channelFilter ? [] : ["-ac", "2"];
     if (typeof playbackRate === "object") {
-        const graph = buildRampFilterComplex(playbackRate, duration, headFilter, channelFilter);
+        const graph = buildRampFilterComplex(playbackRate, duration, headFilter, channelFilter, stream ?? "0:a");
         return ["-filter_complex", graph, "-map", "[out]", ...outputArgs];
     }
     const filters = [headFilter, channelFilter, buildAtempoFilter(playbackRate)].filter(Boolean);
     if (filters.length > 0)
         outputArgs.push("-af", filters.join(","));
-    return outputArgs;
+    return [...(stream ? ["-map", stream] : []), ...outputArgs];
 }
 function escapeExpressionCommas(expression) {
     return expression.replace(/\\/g, "\\\\").replace(/,/g, "\\,");
@@ -545,7 +545,7 @@ async function extractAudioSegment(srcPath, outputPath, stage, mediaStart, durat
             const cycle = await extractAudioSegment(srcPath, cyclePath, stage, mediaStart, loopDuration, 1, signal, config, audioSidecarUrl, { padToDuration: true });
             if (!cycle.success)
                 return { ...cycle, outputPath };
-            const outputArgs = preparedAudioOutputArgs(metadata, normalizedPlaybackRate, duration, null);
+            const outputArgs = preparedAudioOutputArgs(metadata, normalizedPlaybackRate, duration, null, null);
             const result = await runFfmpeg([
                 "-stream_loop",
                 "-1",
@@ -591,7 +591,7 @@ async function extractAudioSegment(srcPath, outputPath, stage, mediaStart, durat
         ...(options?.padToDuration ? ["apad"] : []),
     ]
         .filter(Boolean)
-        .join(",") || null);
+        .join(",") || null, metadata ? `0:a:${metadata.audioStream}` : null);
     const readFrom = fromSidecar ? audioSidecarUrl : srcPath;
     const args = [
         ...(readsUrl ? FAIL_ON_READ_ERROR_INSTEAD_OF_ENDING_THERE : []),

package/dist/services/audioVolumeEnvelope.js

@@ -15,7 +15,7 @@
  * the caller can fall back to the expression path rather than corrupting audio.
  */
 import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "fs";
-import { renameWithRetry } from "../utils/renameWithRetry.js";
+import { renameWithRetry } from "@hyperframes/core/rename-retry";
 import { dirname, join } from "path";
 import { normaliseEnvelope } from "@hyperframes/core/media-volume-envelope";
 import { riffChunks, wavFormatTag } from "./wavChunks.js";

package/dist/services/browserManager.d.ts

@@ -61,32 +61,6 @@ export declare const _closeBrowserAfterFailedProbeForTests: typeof closeBrowserA
 export declare function _resetAutoBrowserGpuModeCacheForTests(): void;
 /** True when a `resolvedMode` render must launch without WAYLAND_DISPLAY to reach the GPU. */
 export declare function captureWithoutWaylandDisplay(resolvedMode: "software" | "hardware"): Promise<boolean>;
-/**
- * Resolve `browserGpuMode` to a concrete `"software" | "hardware"` answer.
- *
- * For `"software"` this is a pure pass-through. For `"auto"` it launches a
- * tiny Chrome with the platform's hardware GPU args, runs a one-shot WebGL
- * availability probe, and falls back to `"software"` if hardware-mode WebGL
- * is unavailable. The Promise is cached for the process lifetime, so
- * concurrent callers (parallel workers) share the same probe.
- *
- * `"hardware"` (an explicit `--browser-gpu` / `PRODUCER_BROWSER_GPU_MODE=
- * hardware`) is honoured verbatim — the operator asked for it — but runs the
- * SAME probe to VERIFY it, because Chrome's hardware GL args are advisory:
- * with no usable GPU in the sandbox (no `/dev/dri`, no NVIDIA container
- * runtime, missing EGL/driver libraries) Chrome silently falls back to
- * software WebGL and the render just runs at CPU speed. Without this check
- * the only trace is a buried `Automatic fallback to software WebGL` browser
- * warning — heygen-com/hyperframes#2967 rendered 19186 frames on CPU while
- * `--browser-gpu` was set and nothing said so. The probe result never
- * changes the returned mode; it only makes the fallback loud.
- *
- * Any probe failure (Chrome launch error, navigation timeout, missing canvas
- * API, etc.) is treated as a `"software"` result. The render path with
- * SwiftShader always works, so a misclassification toward software is the
- * safe failure mode; misclassifying toward hardware would error on the real
- * render.
- */
 export declare function resolveBrowserGpuMode(mode: EngineConfig["browserGpuMode"], options?: GpuProbeOptions): Promise<"software" | "hardware">;
 type BrowserLaunchConfig = Partial<Pick<EngineConfig, "browserTimeout" | "protocolTimeout" | "chromePath" | "forceScreenshot">> & {
     withoutWaylandDisplay?: boolean;

package/dist/services/browserManager.js

@@ -5,7 +5,9 @@
  * Manages Puppeteer browser lifecycle: Chrome executable resolution,
  * launch args, pooled browser acquisition/release.
  */
+import { explainChromeLaunchFailure } from "./chromeStartup.js";
 import { withHyperframesBrowserMarker } from "@hyperframes/core/browser-marker";
+import { inAgentSandbox, machServiceDenied, oneProcessOverPipe, pipeLaunchClosedOnMac, sandboxDeniedRemediation, } from "./sandboxLaunch.js";
 import { scanHtmlOpeningTags } from "@hyperframes/parsers/html-attribute-spans";
 import { execSync } from "child_process";
 import { existsSync, readdirSync, statSync } from "fs";
@@ -462,7 +464,8 @@ async function probeWebGlMode(ppt, options, env, label = "") {
     }
     catch (err) {
         logResolvedBrowserGpuMode("software", label + formatProbeFailure(err));
-        return { mode: "software", cause: "probe-error" };
+        const aborted = err instanceof Error && err.name === "AbortError";
+        return { mode: "software", cause: "probe-error", ...(aborted && { aborted }) };
     }
 }
 function envWithoutWaylandDisplay() {
@@ -524,12 +527,24 @@ function wslAccess(options) {
  * safe failure mode; misclassifying toward hardware would error on the real
  * render.
  */
+async function sharedGpuProbe(options) {
+    const shared = (_autoBrowserGpuModeCache ??= probeAutoBrowserGpuMode(options));
+    const outcome = await shared;
+    if (!outcome.aborted)
+        return outcome;
+    if (_autoBrowserGpuModeCache === shared)
+        _autoBrowserGpuModeCache = undefined;
+    const own = await probeAutoBrowserGpuMode(options);
+    if (!own.aborted)
+        _autoBrowserGpuModeCache ??= Promise.resolve(own);
+    return own;
+}
 export function resolveBrowserGpuMode(mode, options = {}) {
     if (mode === "software")
         return Promise.resolve(mode);
-    _autoBrowserGpuModeCache ??= probeAutoBrowserGpuMode(options);
+    const probe = sharedGpuProbe(options);
     if (mode === "auto") {
-        return _autoBrowserGpuModeCache.then((probed) => {
+        return probe.then((probed) => {
             if (probed.mode === "software" && probed.wslAccess && !_wslSoftwareNoteLogged) {
                 _wslSoftwareNoteLogged = true;
                 console.error(buildWslSoftwareNote(probed));
@@ -537,7 +552,7 @@ export function resolveBrowserGpuMode(mode, options = {}) {
             return probed.mode;
         });
     }
-    return _autoBrowserGpuModeCache.then((probed) => {
+    return probe.then((probed) => {
         // Warn once per cache lifetime, not once per caller: `createCaptureSession`
         // resolves the mode for the probe browser AND every parallel worker, so
         // an un-deduplicated warning prints N+1 times and buries itself.
@@ -652,13 +667,27 @@ export async function acquireBrowser(chromeArgs, config) {
     const enablePool = config?.enableBrowserPool ?? DEFAULT_CONFIG.enableBrowserPool;
     return browserLeasePool.acquire(createBrowserLaunchFingerprint(chromeArgs, config), enablePool);
 }
+/** An agent's macOS seatbelt allows one launch shape only: Chrome in one process over a pipe. */
+async function launchInsideSandbox(ppt, options) {
+    const sandboxed = inAgentSandbox();
+    try {
+        return await ppt.launch(sandboxed ? oneProcessOverPipe(options) : options);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : "";
+        const refused = machServiceDenied(message) || pipeLaunchClosedOnMac(error);
+        if (process.platform !== "darwin" || sandboxed || !refused)
+            throw error;
+        return ppt.launch(oneProcessOverPipe(options));
+    }
+}
 // fallow-ignore-next-line complexity
 async function launchBrowser(fingerprint) {
     const ppt = await getPuppeteer();
     const env = launchEnv(fingerprint);
     let captureMode = fingerprint.requestedCaptureMode;
     let browser;
-    const launch = (args) => ppt.launch({
+    const launch = (args) => launchInsideSandbox(ppt, {
         ...ownedLaunchOptions(),
         headless: true,
         args: withHyperframesBrowserMarker(args),
@@ -667,6 +696,16 @@ async function launchBrowser(fingerprint) {
         env,
         timeout: fingerprint.browserTimeoutMs,
         protocolTimeout: fingerprint.protocolTimeoutMs,
+    }).catch(async (error) => {
+        const remediation = process.platform === "darwin" &&
+            sandboxDeniedRemediation(error instanceof Error ? error.message : "");
+        if (remediation)
+            throw new Error(remediation, { cause: error });
+        const defaults = await ppt.defaultArgs({
+            headless: true,
+            args: withHyperframesBrowserMarker(args),
+        });
+        throw await explainChromeLaunchFailure(error, fingerprint.executablePath, defaults);
     });
     const probe = (target, timeoutMs) => probeBeginFrameSupport(target, timeoutMs).catch((error) => ({
         supported: true,

package/dist/services/chromeHostCeiling.d.ts

@@ -7,7 +7,7 @@ export declare const isManagedChromeDir: (versionName: string) => boolean;
 /** Newest first, by numeric build (`linux-148.0.1` before `linux-99.0.1`). */
 export declare function compareBrowserVersionsDescending(left: string, right: string): number;
 /** Whether a shell loads a blank page and exits: an old build can die at launch on a newer OS. Asked once per path. */
-export declare function shellStarts(binary: string): boolean;
+export declare function shellStarts(binary: string, timeoutMs?: number): boolean;
 /** The shared Puppeteer cache's shell: the managed build, else the newest under the host's ceiling that starts.
  * `shell` names a version dir's executable, or undefined when it holds no usable file. */
 export declare function pickSharedShell(versions: readonly string[], shell: (version: string) => string | undefined): string | undefined;

package/dist/services/chromeHostCeiling.js

@@ -52,11 +52,13 @@ export function compareBrowserVersionsDescending(left, right) {
 const starts = new Map();
 const debug = debuglog("hyperframes:browser");
 /** Whether a shell loads a blank page and exits: an old build can die at launch on a newer OS. Asked once per path. */
-export function shellStarts(binary) {
+export function shellStarts(binary, timeoutMs = 10_000) {
     let answer = starts.get(binary);
     if (answer === undefined) {
         const probe = ["--no-sandbox", "--dump-dom", "about:blank"];
-        answer = spawnSync(binary, probe, { stdio: "ignore", timeout: 10_000 })?.status === 0;
+        answer =
+            spawnSync(binary, probe, { stdio: "ignore", timeout: timeoutMs, killSignal: "SIGKILL" })
+                ?.status === 0;
         if (!answer)
             debug("skipping %s: it did not start", binary);
         starts.set(binary, answer);

package/dist/services/chromeStartup.d.ts

@@ -0,0 +1,10 @@
+/** Names an exit code the way a person can act on it; undefined when it has no name. */
+export declare function nameChromeExit(code: number | null, platform?: NodeJS.Platform): string | undefined;
+/** Starts the browser once more with the failed launch's flags and says how it ended. */
+export declare function diagnoseChromeStartup(executablePath: string, args: readonly string[], options?: {
+    timeoutMs?: number;
+    platform?: NodeJS.Platform;
+    signal?: AbortSignal;
+}): Promise<string>;
+/** The launch error, with the startup diagnosis appended; the original stays as `cause`. */
+export declare function explainChromeLaunchFailure(error: unknown, executablePath: string | undefined, args: readonly string[] | undefined, signal?: AbortSignal): Promise<unknown>;

package/dist/services/chromeStartup.js

@@ -0,0 +1,85 @@
+import { spawn } from "node:child_process";
+import { mkdtempSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { removeTreeBestEffort } from "@hyperframes/core/remove-tree";
+const STDERR_TAIL_LINES = 8;
+const PROBE_TIMEOUT_MS = 8_000;
+// NTSTATUS codes a Windows process dies with before it can print anything.
+const WINDOWS_EXITS = [
+    [0xc0000135, "0xC0000135: a required runtime or DLL is missing (Visual C++ runtime)."],
+    [0xc0000017, "0xC0000017: Windows had no memory to start it (out of memory)."],
+    [0xc0000142, "0xC0000142: a DLL failed to initialise, often security software blocking it."],
+    [0xc0000022, "0xC0000022: access denied, often antivirus or a policy blocking the executable."],
+    [0xc000007b, "0xC000007B: the executable and a DLL do not match (32-bit and 64-bit)."],
+];
+/** Names an exit code the way a person can act on it; undefined when it has no name. */
+export function nameChromeExit(code, platform = process.platform) {
+    if (platform !== "win32" || code === null)
+        return undefined;
+    const unsigned = code >>> 0;
+    return WINDOWS_EXITS.find(([known]) => known === unsigned)?.[1];
+}
+function startupArgs(args, profile) {
+    const kept = args.filter((arg) => arg.startsWith("--") &&
+        !arg.startsWith("--remote-debugging") &&
+        !arg.startsWith("--user-data-dir"));
+    return [...kept, `--user-data-dir=${profile}`, "--remote-debugging-port=0", "about:blank"];
+}
+function tail(stderr) {
+    return stderr
+        .split(/\r?\n/)
+        .map((line) => line.trim())
+        .filter(Boolean)
+        .slice(-STDERR_TAIL_LINES)
+        .join("\n");
+}
+/** Starts the browser once more with the failed launch's flags and says how it ended. */
+export async function diagnoseChromeStartup(executablePath, args, options = {}) {
+    const profile = mkdtempSync(join(tmpdir(), "hf-chrome-probe-"));
+    const timeoutMs = options.timeoutMs ?? PROBE_TIMEOUT_MS;
+    try {
+        return await new Promise((resolve) => {
+            let stderr = "";
+            const child = spawn(executablePath, startupArgs(args, profile), {
+                stdio: ["ignore", "ignore", "pipe"],
+                windowsHide: true,
+            });
+            const timer = setTimeout(() => {
+                child.kill();
+                resolve(`Chrome started and kept running for ${timeoutMs} ms when launched on its own.`);
+            }, timeoutMs);
+            options.signal?.addEventListener("abort", () => {
+                clearTimeout(timer);
+                child.kill();
+                resolve("The startup check was cancelled.");
+            }, { once: true });
+            child.stderr.on("data", (chunk) => {
+                stderr = (stderr + chunk.toString()).slice(-4000);
+            });
+            child.once("error", (error) => {
+                clearTimeout(timer);
+                resolve(`Chrome could not be started: ${error.message}`);
+            });
+            child.once("exit", (code, signal) => {
+                clearTimeout(timer);
+                const how = signal ? `was stopped by ${signal}` : `exited with code ${code}`;
+                const named = nameChromeExit(code, options.platform);
+                const lines = tail(stderr);
+                resolve([`Chrome ${how} when launched on its own.`, named, lines && `stderr:\n${lines}`]
+                    .filter(Boolean)
+                    .join("\n"));
+            });
+        });
+    }
+    finally {
+        removeTreeBestEffort(profile);
+    }
+}
+/** The launch error, with the startup diagnosis appended; the original stays as `cause`. */
+export async function explainChromeLaunchFailure(error, executablePath, args, signal) {
+    if (!executablePath || !(error instanceof Error))
+        return error;
+    const diagnosis = await diagnoseChromeStartup(executablePath, args ?? [], { signal });
+    return new Error(`${error.message}\n${diagnosis}`, { cause: error });
+}

package/dist/services/extractionCache.js

@@ -33,7 +33,7 @@
  */
 import { createHash, randomUUID } from "node:crypto";
 import { createReadStream, existsSync, lstatSync, mkdirSync, readdirSync, rmSync, statSync, utimesSync, writeFileSync, } from "node:fs";
-import { renameWithRetry } from "../utils/renameWithRetry.js";
+import { renameWithRetry } from "@hyperframes/core/rename-retry";
 import { join } from "node:path";
 import { FRAME_FILENAME_PREFIX, framePathsFromDirectory } from "./extractedFrameIndex.js";
 /** Filename prefix for extracted frames. Shared with the extractor. */

package/dist/services/parallelCoordinator.d.ts

@@ -239,6 +239,8 @@ export interface ParallelCaptureHooks {
      */
     onWorkerFailure?: (failure: CaptureFailure) => void;
     onWorkerOperation?: (diagnostic: ParallelWorkerPhaseDiagnostic) => void;
+    /** Worker 0 runs this on its initialised session; the other workers wait for it. A rejection fails the pool. */
+    verifyFirstSession?: (session: CaptureSession) => Promise<void>;
 }
 /**
  * The pool's single failure gate. Both halves of the contract the streaming

package/dist/services/parallelCoordinator.js

@@ -7,7 +7,7 @@
 import { cpus, freemem } from "os";
 import { existsSync, mkdirSync, readdirSync } from "fs";
 import { copyFile, readFile } from "fs/promises";
-import { renameWithRetryAsync } from "../utils/renameWithRetry.js";
+import { renameWithRetryAsync } from "@hyperframes/core/rename-retry";
 import { join } from "path";
 import { getHeapStatistics } from "v8";
 import { createCaptureSession, initializeSession, closeCaptureSession, captureFrame, captureFrameToBufferPipelined, captureFrameToBuffer, getCapturePerfSummary, DrawElementVerificationError, } from "./frameCapture.js";
@@ -552,7 +552,7 @@ export async function verifyDiskDrawElementSamples(session, task, streaming) {
 // flagged only because the disk self-verify call shifted its line range into
 // the changed-code audit. Not restructured by this PR.
 // fallow-ignore-next-line complexity
-async function executeWorkerTask(task, serverUrl, captureOptions, createBeforeCaptureHook, signal, onFrameCaptured, onFrameBuffer, config, parallel, onFailure, onWorkerPhase, onWorkerOperation) {
+async function executeWorkerTask(task, serverUrl, captureOptions, createBeforeCaptureHook, signal, onFrameCaptured, onFrameBuffer, config, parallel, onFailure, onWorkerPhase, onWorkerOperation, gate) {
     const startTime = Date.now();
     let framesCaptured = 0;
     if (!existsSync(task.outputDir))
@@ -603,6 +603,8 @@ async function executeWorkerTask(task, serverUrl, captureOptions, createBeforeCa
                 await assertSwiftShader(activeSession.page, readWebGlVendorInfoFromCanvas);
             }
             await initializeSession(activeSession);
+            if (gate)
+                await (task.workerId === 0 ? gate.verify(activeSession) : gate.wait());
         });
         canvasDrawElement = activeSession.captureMode === "drawelement";
         gpuBackend = activeSession.gpuRenderer ?? "unknown";
@@ -622,6 +624,8 @@ async function executeWorkerTask(task, serverUrl, captureOptions, createBeforeCa
         };
     }
     catch (error) {
+        if (task.workerId === 0)
+            gate?.fail(error);
         const diagnostics = session ? selectWorkerDiagnostics(session.browserConsoleBuffer) : [];
         const workerDiagnostic = {
             workerId: task.workerId,
@@ -687,6 +691,23 @@ export function isPoolFatalWorkerFailure(failure, streaming) {
         return failure.kind !== "cancelled";
     return isFatalCaptureFailure(failure);
 }
+function createFirstSessionGate(verify) {
+    let fail;
+    let pass;
+    const settled = new Promise((resolve, reject) => {
+        pass = resolve;
+        fail = reject;
+    });
+    settled.catch(() => { });
+    return {
+        verify: (session) => verify(session).then(pass, (error) => {
+            fail(error);
+            throw error;
+        }),
+        wait: () => settled,
+        fail,
+    };
+}
 function pageErrorLinesOf(session) {
     return session.browserConsoleBuffer.filter((line) => line.includes("PAGEERROR"));
 }
@@ -777,7 +798,8 @@ export async function executeParallelCapture(serverUrl, workDir, tasks, captureO
         hooks,
     });
     const onFailure = failureHandler.onFailure;
-    const results = await Promise.all(tasks.map((task) => executeWorkerTask(task, serverUrl, workerCaptureOptions, createBeforeCaptureHook, workerSignal, onFrameCaptured, onFrameBuffer, config, parallel, onFailure, onWorkerPhase, hooks?.onWorkerOperation)));
+    const gate = hooks?.verifyFirstSession && createFirstSessionGate(hooks.verifyFirstSession);
+    const results = await Promise.all(tasks.map((task) => executeWorkerTask(task, serverUrl, workerCaptureOptions, createBeforeCaptureHook, workerSignal, onFrameCaptured, onFrameBuffer, config, parallel, onFailure, onWorkerPhase, hooks?.onWorkerOperation, gate)));
     flagSilentWorkerExits(results);
     const errors = results.filter((r) => r.failure || r.error);
     if (errors.length > 0) {

package/dist/services/sandboxLaunch.d.ts

@@ -0,0 +1,10 @@
+import type { LaunchOptions } from "puppeteer-core";
+export declare function machServiceDenied(errorMessage: string): boolean;
+export declare function pipeLaunchClosedOnMac(error: unknown, platform?: NodeJS.Platform): boolean;
+/** Codex runs agent commands in a macOS seatbelt, which names itself in the environment. */
+export declare function inAgentSandbox(env?: NodeJS.ProcessEnv, platform?: NodeJS.Platform): boolean;
+/** The one launch a seatbelt allows: no child process registers a mach port, nothing listens, no GPU composites. */
+export declare function oneProcessOverPipe(options: LaunchOptions): LaunchOptions;
+export declare function isOneProcessOverPipe(options: LaunchOptions): boolean;
+/** A process sandbox (an agent's macOS seatbelt) refused Chrome its mach service, so no browser starts here. */
+export declare function sandboxDeniedRemediation(errorMessage: string): string | undefined;

package/dist/services/sandboxLaunch.js

@@ -0,0 +1,31 @@
+const MACH_SERVICE_DENIED = /bootstrap_check_in\b[^\n]*Permission denied/;
+const SINGLE_PROCESS = "--single-process";
+const CPU_COMPOSITING = "--disable-gpu-compositing";
+export function machServiceDenied(errorMessage) {
+    return MACH_SERVICE_DENIED.test(errorMessage);
+}
+export function pipeLaunchClosedOnMac(error, platform = process.platform) {
+    return platform === "darwin" && error instanceof Error && error.name === "TargetCloseError";
+}
+/** Codex runs agent commands in a macOS seatbelt, which names itself in the environment. */
+export function inAgentSandbox(env = process.env, platform = process.platform) {
+    return platform === "darwin" && env.CODEX_SANDBOX === "seatbelt";
+}
+/** The one launch a seatbelt allows: no child process registers a mach port, nothing listens, no GPU composites. */
+export function oneProcessOverPipe(options) {
+    const args = options.args ?? [];
+    const missing = [SINGLE_PROCESS, CPU_COMPOSITING].filter((flag) => !args.includes(flag));
+    return { ...options, pipe: true, args: [...args, ...missing] };
+}
+export function isOneProcessOverPipe(options) {
+    return options.pipe === true && (options.args ?? []).includes(SINGLE_PROCESS);
+}
+/** A process sandbox (an agent's macOS seatbelt) refused Chrome its mach service, so no browser starts here. */
+export function sandboxDeniedRemediation(errorMessage) {
+    if (!machServiceDenied(errorMessage))
+        return undefined;
+    return [
+        "The browser can't start inside this sandbox: macOS refused Chrome's mach service (bootstrap_check_in: Permission denied).",
+        "Rerun this command with escalation, outside the sandbox.",
+    ].join("\n");
+}

package/dist/services/videoFrameExtractor.d.ts

@@ -188,6 +188,8 @@ export interface VideoExtractionFailure {
      * can contain a local path or a signed source URL.
      */
     error: string;
+    /** ffmpeg's last stderr lines, without paths or URLs: what a producer-facing error may say. */
+    ffmpegReason?: string;
 }
 export type VideoExtractionFailureStatusClass = "http_4xx" | "http_5xx" | "timeout" | "network" | "other";
 export interface VideoExtractionFailureRetry {
@@ -211,8 +213,9 @@ export declare class VideoSourceExtractionError extends Error {
     readonly kind: VideoExtractionFailureKind;
     readonly retryable: boolean;
     readonly diagnostic: string;
+    readonly ffmpegReason?: string | undefined;
     readonly hyperframesVideoSourceExtractionError: true;
-    constructor(kind: VideoExtractionFailureKind, retryable: boolean, message: string, diagnostic?: string);
+    constructor(kind: VideoExtractionFailureKind, retryable: boolean, message: string, diagnostic?: string, ffmpegReason?: string | undefined);
 }
 export declare function isVideoSourceExtractionError(error: unknown): error is VideoSourceExtractionError;
 /**

package/dist/services/videoFrameExtractor.js

@@ -7,7 +7,7 @@
  */
 import { audioGroupsById, isMemberGroupHidden, isSelfOrAncestorHidden } from "./mediaHidden.js";
 import { copyFileSync, existsSync, linkSync, mkdirSync, rmSync } from "fs";
-import { join } from "path";
+import { basename, join } from "path";
 import { cpus } from "os";
 import { createConcurrencyLimit } from "../utils/concurrencyLimit.js";
 import { parseHTML } from "linkedom";
@@ -208,15 +208,34 @@ export class VideoSourceExtractionError extends Error {
     kind;
     retryable;
     diagnostic;
+    ffmpegReason;
     hyperframesVideoSourceExtractionError = true;
-    constructor(kind, retryable, message, diagnostic = message) {
+    constructor(kind, retryable, message, diagnostic = message, ffmpegReason) {
         super(message);
         this.kind = kind;
         this.retryable = retryable;
         this.diagnostic = diagnostic;
+        this.ffmpegReason = ffmpegReason;
         this.name = "VideoSourceExtractionError";
     }
 }
+const FFMPEG_REASON_LINES = 3;
+const FFMPEG_REASON_CHARS = 300;
+/** ffmpeg's last stderr lines for an error that leaves this host: no local path, file name or URL. */
+function ffmpegReasonFrom(stderr, paths) {
+    let text = stderr;
+    for (const known of paths.filter(Boolean).sort((a, b) => b.length - a.length))
+        text = text.split(known).join("<path>");
+    return text
+        .replace(/[a-z][a-z\d+.-]*:\/\/[^\s'"]+/gi, "<url>")
+        .replace(/(?:[a-z]:)?(?:[\\/][^\s\\/:'"]+){2,}/gi, "<path>")
+        .split(/\r?\n/)
+        .map((line) => line.trim())
+        .filter(Boolean)
+        .slice(-FFMPEG_REASON_LINES)
+        .join(" | ")
+        .slice(-FFMPEG_REASON_CHARS);
+}
 export function isVideoSourceExtractionError(error) {
     return (typeof error === "object" &&
         error !== null &&
@@ -745,13 +764,18 @@ outputDirOverride) {
         const timeoutSuffix = timedOut ? ` (no new frame for ${ffmpegProcessTimeout} ms)` : "";
         const diagnostic = `${hdrPrefix}FFmpeg exited with code ${processResult.exitCode}${timeoutSuffix}: ` +
             processResult.stderr.slice(-500);
+        const ffmpegReason = ffmpegReasonFrom(processResult.stderr, [
+            videoPath,
+            basename(videoPath),
+            videoOutputDir,
+        ]);
         if (timedOut) {
-            throw new VideoSourceExtractionError("ffmpeg_timeout", true, "Video frame extraction timed out", diagnostic);
+            throw new VideoSourceExtractionError("ffmpeg_timeout", true, "Video frame extraction timed out", diagnostic, ffmpegReason);
         }
         const transientIo = /resource temporarily unavailable|device or resource busy|input\/output error/i.test(processResult.stderr);
         throw new VideoSourceExtractionError(transientIo ? "ffmpeg_transient" : "ffmpeg_failed", transientIo, transientIo
             ? "Video frame extraction hit a transient I/O failure"
-            : "Video source could not be decoded", diagnostic);
+            : "Video source could not be decoded", diagnostic, ffmpegReason);
     }
     const framePaths = framePathsFromDirectory(videoOutputDir, format, !!options.frameRanges);
     if (framePaths.size === 0 && duration > 0) {
@@ -1223,13 +1247,9 @@ export async function extractAllVideoFrames(videos, baseDir, options, signal, co
             resolvedVideos.push({ video, videoPath });
         }
         catch (err) {
-            const classified = classifyVideoExtractionError(err);
             errors.push({
-                videoId: video.id,
-                kind: classified.kind,
-                retryable: classified.retryable,
+                ...extractionError(video.id, err),
                 ...(err instanceof UrlDownloadError ? { group: downloadFailureGroup(video.src, err) } : {}),
-                error: classified.diagnostic,
             });
         }
     }
@@ -1417,6 +1437,7 @@ export async function extractAllVideoFrames(videos, baseDir, options, signal, co
             kind: classified.kind,
             retryable: classified.retryable,
             error: classified.diagnostic,
+            ...(classified.ffmpegReason ? { ffmpegReason: classified.ffmpegReason } : {}),
         };
     }
     function scopedExtractionOptions(work) {
@@ -1775,12 +1796,7 @@ export async function extractAllVideoFrames(videos, baseDir, options, signal, co
                 ? `[shared extraction, leader ${outcome.error.videoId}] ${outcome.error.error}`
                 : outcome.error.error;
             results.push({
-                error: {
-                    videoId: prepared.work.video.id,
-                    kind: outcome.error.kind,
-                    retryable: outcome.error.retryable,
-                    error: message,
-                },
+                error: { ...outcome.error, videoId: prepared.work.video.id, error: message },
             });
             continue;
         }

package/dist/utils/ffprobe.d.ts

@@ -61,6 +61,8 @@ export interface AudioMetadata {
     latestStreamLeadSeconds?: number;
     audioStreamLeadSeconds?: number;
     audioStreamCount?: number;
+    /** The track read for these facts and for the mix, by its place among the audio streams (decodableAudioStream). */
+    audioStream: number;
 }
 interface FFProbeStream {
     codec_type: string;

package/dist/utils/ffprobe.js

@@ -8,6 +8,7 @@ import { basename, join } from "path";
 import { redactTelemetryString } from "@hyperframes/core";
 import { alphaDecoderFor, pixelFormatHasAlpha, videoStreamHasAlpha, } from "@hyperframes/parsers/media-alpha";
 import { urlInputArgs } from "./urlInput.js";
+import { decodableAudioStream } from "@hyperframes/parsers/media-streams";
 import { runFfmpeg } from "./runFfmpeg.js";
 import { FFPROBE_PATH_ENV, getFfprobeBinary } from "./ffmpegBinaries.js";
 import { ManagedChildProcess } from "./managedChildProcess.js";
@@ -445,7 +446,7 @@ export async function probeMediaProfile(filePath, options) {
         }
         return {
             hasVideoStream: videoStreams.length > 0,
-            hasAudioStream: output.streams.some((stream) => stream.codec_type === "audio"),
+            hasAudioStream: decodableAudioStream(output.streams) !== null,
             visualKind: isStillImage ? "still" : hasMovingVideoStream ? "moving" : "none",
         };
     }
@@ -790,7 +791,7 @@ export async function extractMediaMetadata(filePath) {
             height: videoStream.height || stillImage()?.height || 0,
             fps,
             videoCodec: videoStream.codec_name || "unknown",
-            hasAudio: output?.streams.some((s) => s.codec_type === "audio") ?? false,
+            hasAudio: decodableAudioStream(output?.streams ?? []) !== null,
             isVFR,
             hasAlpha,
             ...(alphaPlaneDecoded === undefined ? {} : { alphaPlaneDecoded }),
@@ -956,8 +957,10 @@ export async function extractAudioMetadata(filePath, options) {
 }
 async function probeAudioMetadata(filePath, signal) {
     const output = await probeMediaOutput(filePath, signal);
-    const audioStream = output.streams.find((s) => s.codec_type === "audio");
-    if (!audioStream)
+    const audioStreams = output.streams.filter((s) => s.codec_type === "audio");
+    const audioStreamIndex = decodableAudioStream(output.streams);
+    const audioStream = audioStreamIndex === null ? undefined : audioStreams[audioStreamIndex];
+    if (audioStreamIndex === null || !audioStream)
         throw new Error("[FFmpeg] No audio stream found");
     let durationSeconds = output.format.duration ? parseFloat(output.format.duration) : 0;
     const streamDuration = audioStream.duration ? parseFloat(audioStream.duration) : undefined;
@@ -966,7 +969,7 @@ async function probeAudioMetadata(filePath, signal) {
     // Container summaries can undercount intact audio, so the decoded last frame wins.
     // The probe returns null instead of throwing: a throw here drops the audio element.
     if (sampleRate > 0) {
-        const decoded = await probeDecodedAudioDuration(filePath, sampleRate, audioStartSeconds(audioStream, output.format), durationSeconds, signal);
+        const decoded = await probeDecodedAudioDuration(filePath, audioStreamIndex, sampleRate, audioStartSeconds(audioStream, output.format), durationSeconds, signal);
         if (decoded !== null) {
             durationSeconds = reconcileAudioDuration(durationSeconds, decoded, output.format);
         }
@@ -980,7 +983,8 @@ async function probeAudioMetadata(filePath, signal) {
         bitrate: output.format.bit_rate ? parseInt(output.format.bit_rate) : undefined,
         latestStreamLeadSeconds: latestStreamLeadSeconds(output),
         audioStreamLeadSeconds: streamLeadSeconds(output, audioStream),
-        audioStreamCount: output.streams.filter((s) => s.codec_type === "audio").length,
+        audioStreamCount: audioStreams.length,
+        audioStream: audioStreamIndex,
     };
 }
 /** Chrome's media time 0 is the earliest of these; a stream starting later plays that much in. */
@@ -1018,11 +1022,11 @@ function reconcileAudioDuration(containerSeconds, decodedSeconds, format) {
  * True audio duration from the last decoded frame (timestamp + nb_samples - stream start): tail
  * first, then the whole file if a bad seek finds nothing. Null, never a throw, except on abort.
  */
-async function probeDecodedAudioDuration(filePath, sampleRate, startSeconds, containerDurationSeconds, signal) {
+async function probeDecodedAudioDuration(filePath, audioStream, sampleRate, startSeconds, containerDurationSeconds, signal) {
     const probe = async (readInterval) => {
         const args = [
             "-select_streams",
-            "a:0",
+            `a:${audioStream}`,
             "-show_entries",
             "frame=best_effort_timestamp_time,nb_samples",
             "-of",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperframes/engine",
-  "version": "0.8.207",
+  "version": "0.8.209",
   "description": "Seekable web page to video rendering engine (Puppeteer + FFmpeg)",
   "repository": {
     "type": "git",
@@ -27,6 +27,10 @@
       "import": "./dist/services/chromeHostCeiling.js",
       "types": "./dist/services/chromeHostCeiling.d.ts"
     },
+    "./chrome-startup": {
+      "import": "./dist/services/chromeStartup.js",
+      "types": "./dist/services/chromeStartup.d.ts"
+    },
     "./system-memory": {
       "import": "./dist/services/systemMemory.js",
       "types": "./dist/services/systemMemory.d.ts"
@@ -50,8 +54,8 @@
     "linkedom": "^0.18.12",
     "puppeteer": "^25.8.0",
     "puppeteer-core": "^25.8.0",
-    "@hyperframes/core": "^0.8.207",
-    "@hyperframes/parsers": "^0.8.207"
+    "@hyperframes/parsers": "^0.8.209",
+    "@hyperframes/core": "^0.8.209"
   },
   "devDependencies": {
     "@types/node": "^25.0.10",

package/dist/utils/removeScratch.d.ts

@@ -1,5 +0,0 @@
-/** Removes a scratch folder or file the mix is already done with. A refusal (Windows temp folders that deny
- * delete) leaves it for the render's own cleanup and never fails the audio it served. */
-export declare function removeScratch(path: string): void;
-/** Runs `run`; whatever removeScratch left behind inside it (this run's only) goes to `report` once it ends. */
-export declare function collectScratchLeftovers<T>(run: () => Promise<T>, report: (left: string[]) => void): Promise<T>;

package/dist/utils/removeScratch.js

@@ -1,23 +0,0 @@
-import { AsyncLocalStorage } from "node:async_hooks";
-import { rmSync } from "node:fs";
-const collecting = new AsyncLocalStorage();
-/** Removes a scratch folder or file the mix is already done with. A refusal (Windows temp folders that deny
- * delete) leaves it for the render's own cleanup and never fails the audio it served. */
-export function removeScratch(path) {
-    try {
-        rmSync(path, { recursive: true, force: true });
-    }
-    catch {
-        collecting.getStore()?.push(path);
-    }
-}
-/** Runs `run`; whatever removeScratch left behind inside it (this run's only) goes to `report` once it ends. */
-export async function collectScratchLeftovers(run, report) {
-    const left = [];
-    try {
-        return await collecting.run(left, run);
-    }
-    finally {
-        report(left);
-    }
-}

package/dist/utils/renameWithRetry.d.ts

@@ -1,16 +0,0 @@
-interface Options {
-    platform?: NodeJS.Platform;
-    /** Copy the bytes when Windows keeps refusing (a TEMP that denies delete). Not atomic: scratch files only. */
-    copyFallback?: boolean;
-}
-/** `renameSync` that rides out Windows' transient file locks; other platforms and errors throw at once. */
-export declare function renameWithRetry(from: string, to: string, options?: Options & {
-    rename?: (from: string, to: string) => void;
-    copy?: (from: string, to: string) => void;
-}): void;
-/** Async twin of {@link renameWithRetry}. */
-export declare function renameWithRetryAsync(from: string, to: string, options?: Options & {
-    rename?: (from: string, to: string) => Promise<void>;
-    copy?: (from: string, to: string) => Promise<void>;
-}): Promise<void>;
-export {};

package/dist/utils/renameWithRetry.js

@@ -1,81 +0,0 @@
-import { copyFileSync, renameSync } from "node:fs";
-import { copyFile, rename } from "node:fs/promises";
-import { removeScratch } from "./removeScratch.js";
-// Windows reports EPERM/EACCES/EBUSY while antivirus or a just-exited process still holds the
-// file; the hold clears within milliseconds. Total wait before giving up: about 1.3 s.
-const RETRYABLE = new Set(["EPERM", "EACCES", "EBUSY"]);
-const BACKOFF_MS = [10, 20, 40, 80, 160, 320, 640];
-function isRetryable(error, platform) {
-    if (platform !== "win32")
-        return false;
-    return RETRYABLE.has(error?.code ?? "");
-}
-/** What a refused rename does next: wait and try again, fall back to a copy, or give up with the error. */
-function nextStep(error, attempt, options, platform) {
-    if (!isRetryable(error, platform))
-        return "throw";
-    if (attempt < BACKOFF_MS.length)
-        return "wait";
-    return options.copyFallback ? "copy" : "throw";
-}
-function sleepSync(ms) {
-    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
-}
-/** `renameSync` that rides out Windows' transient file locks; other platforms and errors throw at once. */
-export function renameWithRetry(from, to, options = {}) {
-    const doRename = options.rename ?? renameSync;
-    const doCopy = options.copy ?? copyFileSync;
-    const platform = options.platform ?? process.platform;
-    for (let attempt = 0;; attempt++) {
-        try {
-            doRename(from, to);
-            return;
-        }
-        catch (error) {
-            const step = nextStep(error, attempt, options, platform);
-            if (step === "throw")
-                throw error;
-            if (step === "wait") {
-                sleepSync(BACKOFF_MS[attempt]);
-                continue;
-            }
-            try {
-                doCopy(from, to);
-            }
-            catch {
-                throw error;
-            }
-            removeScratch(from);
-            return;
-        }
-    }
-}
-/** Async twin of {@link renameWithRetry}. */
-export async function renameWithRetryAsync(from, to, options = {}) {
-    const doRename = options.rename ?? rename;
-    const doCopy = options.copy ?? copyFile;
-    const platform = options.platform ?? process.platform;
-    for (let attempt = 0;; attempt++) {
-        try {
-            await doRename(from, to);
-            return;
-        }
-        catch (error) {
-            const step = nextStep(error, attempt, options, platform);
-            if (step === "throw")
-                throw error;
-            if (step === "wait") {
-                await new Promise((resolve) => setTimeout(resolve, BACKOFF_MS[attempt]));
-                continue;
-            }
-            try {
-                await doCopy(from, to);
-            }
-            catch {
-                throw error;
-            }
-            removeScratch(from);
-            return;
-        }
-    }
-}