fix(cli): a low-disk render refusal names the extracted-frame cache and clean - #7695

Context: I've been using HyperFrames every day for the past two weeks to make Korean Shorts and long-form videos, and it's been great to work with. This PR is one of a batch of fixes for things I ran into along the way, so you'll see several PRs from me at once — sorry for the pile-up, and thanks for your patience. Each one is reproduced on current main, independent of the others, and can be reviewed, merged or closed on its own.

What

When hyperframes render refuses to start because a volume it needs has under 1 GB free, and HyperFrames' own extracted-frame cache sits on that volume, the message now says how big the cache is, where it is, and that npx hyperframes clean removes it:

✗  Low disk space
   0.5 GB free at /Volumes/hfLowDisk/T
   Renders produce large temp files. Free disk space before rendering. The extracted-frame cache holds 649.5 MB at /Volumes/hfLowDisk/T/hyperframes-extract-cache-501; `npx hyperframes clean` removes what no render used in the last hour.

With no cache, an empty one, or a cache on a different volume (HYPERFRAMES_EXTRACT_CACHE_DIR / --frames-cache-dir elsewhere), the message is unchanged.

Why

On a Mac the render stopped with ✗ Low disk space 0.9 GB free at /var/folders/…/T — Renders produce large temp files. The largest HyperFrames item in that folder was hyperframes-extract-cache-501 at 2.1 GB, with entries from earlier days. That is working as designed: the extractor's LRU sweep holds the cache at extractCacheMaxBytes (2 GiB default, HYPERFRAMES_EXTRACT_CACHE_MAX_MB), and hyperframes clean (#4701) empties it. But a 2 GiB cap is most of what is left on a nearly full disk, and neither the refusal nor its hint mentioned the cache or clean, so the user had to find it by hand. doctor's Frames cache row does flag low space at the cache location, but only suggests relocating it.

Related work

• feat(cli): add hyperframes clean to find and remove what HyperFrames left on disk #4701 added hyperframes clean, which sweeps the extract cache with gcExtractionCache(…, { maxBytes: 0 }).
• feat(cli): surface extract-cache dir in doctor + add --frames-cache-dir sugar #2564 surfaced the extract-cache dir in doctor and added --frames-cache-dir.
• fix(producer): disk-space error suggests --workers 1 only when one worker would stream #5934 tuned the mid-render disk-space error (--workers 1); this is the pre-render refusal in render/execute.ts, a different message.
• No open issue or PR for this (searched "extract cache", "low disk space", "hyperframes clean cache", "disk space").

How

packages/cli/src/commands/render/execute.ts, refuseLowDiskBeforeBrowserDownload: it keeps the path of each failing checkDisk outcome. For each, extractCacheHint(path) resolves the cache dir the render will use (resolveExtractCacheDir(), after applyRenderEnvironment, so --frames-cache-dir counts), checks it exists and is on the same device as the full path (statSync().dev), and sizes it with the engine's directorySizeBytes. The size is only computed on the refusal path, never on a normal render.

The hint says "what no render used in the last hour" because clean keeps entries younger than EXTRACT_CACHE_MIN_AGE_MS (1 h).

docs/packages/cli.mdx (clean section): one line saying the low-disk refusal now points here.

Test plan

• packages/cli/src/commands/render/execute.test.ts, "a render on a nearly full disk": with getFreeDiskMb at 400 MB and HYPERFRAMES_EXTRACT_CACHE_DIR pointing at a 3 MB cache, the refusal contains The extracted-frame cache holds 3.0 MB at <dir> and npx hyperframes clean; with no cache dir it contains neither. On main's execute.ts the cached case fails (expected false to be true); with the fix the file's 16 tests pass.

• Real CLI, with TMPDIR on a 1.2 GB APFS disk image holding 650 MB of real extract-cache entries dated two days back (touch -t):

  # main
  ✗  Low disk space
     0.5 GB free at /Volumes/hfLowDisk/T
     Renders produce large temp files. Free disk space before rendering.
  
  # this branch
  ✗  Low disk space
     0.5 GB free at /Volumes/hfLowDisk/T
     Renders produce large temp files. Free disk space before rendering. The extracted-frame cache holds 649.5 MB at /Volumes/hfLowDisk/T/hyperframes-extract-cache-501; `npx hyperframes clean` removes what no render used in the last hour.
  
  $ npx hyperframes clean
  ◇  Removed 649.5 MB
    Extracted video frames   649.5 MB  /Volumes/hfLowDisk/T/hyperframes-extract-cache-501
  # volume now 1.2 GB free; the same render completes (1.6 MB · 9.0s video · rendered in 4.9s)
  

• Gates: oxlint / oxfmt clean, fallow audit --base origin/main no issues, comment ratchet at or under share, lefthook pre-commit (format, fallow, typecheck, cli-process-ownership) passed.

Not covered

• No automatic eviction: the render still refuses rather than trimming the cache itself. Lowering the cap or sweeping it on a low-disk refusal would change behavior and is left for discussion.
• doctor's disk row and Frames cache row are unchanged.