[miguel-heygen]

What

hyperframes check --prepare-media makes only the browser-playable video copies and exits, and a copy that is stopped continues from its finished pieces instead of starting over.

Why

A long HEVC or ProRes video can take longer to copy into a browser-playable file than a caller allows a check to run. The copy was then killed, left a half-written temp file, and the next check started over from zero, so such a project could never finish checking from a caller with a short clock.

Related work

Stacked on #6104 (same copy path); retarget to main when it merges.

How

• hyperframes check --prepare-media [--json] makes only those copies and exits. It opens no browser and writes no report, and each file stays bounded by the existing 15 minute transcode limit. --json prints { ok, prepared: [{ file, state: "ready" | "cached" | "failed", reason? }], total, ready, failed }; progress stays on stderr. Exit code is 0 when every copy is ready, 1 when any failed. It honors --proxy/--no-proxy and takes the same project lock as a check.
• A source longer than 90 seconds is now copied in one-minute pieces, each finished piece kept under a stable name in the cache, then joined without re-encoding. A copy that is killed, aborted or out of budget loses at most the piece in flight, and the next run (prepare or a normal check or preview) continues from the first missing piece. This lives in the one place every caller of the copy goes through, so preview and publish gain it too. Shorter sources keep the single pass they had.
• Stale pieces (older than an hour) are swept with the existing temp-file sweep.

Test plan

Synthetic 200 s 1080p HEVC with audio, on Linux with ffmpeg 7.0:

Run	Result
Uninterrupted, 4 pieces	50.4 s; 6000 video frames, container 200.02 s
Process and ffmpeg killed at 22 s, then rerun	rerun 29.1 s (22 + 29 is about 51: no restart); 6000 frames, 200.02 s, same bytes as the uninterrupted copy
Real check --prepare-media --json, stopped at 25 s, rerun	rerun 35 s, state: ready, exit 0; a third run reports cached in 3 ms

Tests: new cases for piece resume (the rerun encodes only the missing pieces, then joins and leaves only the final file), short sources staying one pass, stale-piece sweep, and --prepare-media entering through createCheckCommand (no check pipeline call, JSON shape, exit 1 on a failed copy). Removing the "skip a finished piece" line turns the resume test red (expected [ '0', '60', '0', '60', '120' ] to deeply equal [ '0', '60', '60', '120' ]). 3 green runs of the cli check tests (170) and studio-server helpers (523); typecheck and oxlint clean.

• Unit tests added/updated
• Manual testing performed
• Documentation updated (docs/packages/cli.mdx)
• Comments follow CONTRIBUTING.md "Comments"

Not covered:

• A caller that kills the CLI with SIGKILL leaves ffmpeg running to the end of its current piece, and its temp file is swept after an hour. A caller should stop the whole process group.
• Join timing at piece boundaries was checked for frame count and duration on this clip (audio ends 21 ms long over 3 joins), not by ear.

[miguel-heygen]

Folded into #6104 (same copy path, one PR): resumable pieces and check --prepare-media ship there, with the same evidence.