fix(cli): previews and every per-user cache follow HYPERFRAMES_CACHE_DIR - #7224

What

When HYPERFRAMES_CACHE_DIR is set, everything the CLI keeps as a per-user cache goes there. Before, five writers ignored it:

• the background preview's session record and log (XDG_STATE_HOME, else %LOCALAPPDATA% on Windows, else ~/.local/state)
• the registry's manifest cache (~/.hyperframes/cache)
• the local search model (~/.hyperframes/models)
• the catalog vectors, which two readers share (~/.hyperframes/catalog)
• the records of what an app already showed (%LOCALAPPDATA%\hyperframes\catch-up, else ~/.hyperframes/catch-up)

Without HYPERFRAMES_CACHE_DIR, every path stays where it was, so nobody's existing downloads are orphaned.

Why

A Windows report: under an agent sandbox that only allows writes inside the workspace, the default cache folder failed with EPERM. Setting HYPERFRAMES_CACHE_DIR to a workspace folder fixed renders, but "managed preview remained unavailable": preview --background still wrote to %LOCALAPPDATA%\hyperframes\previews and failed with EPERM there. A search of the packages for writes under the home folder, %LOCALAPPDATA% and the XDG folders found the other four cache writers, each the next EPERM under the same sandbox.

Related work

#6716 moved the paths built as ~/.cache/hyperframes onto HYPERFRAMES_CACHE_DIR. These five were built from other folders, so that change and its "every cache path goes through hyperframesCacheDir" test did not catch them.

How

namedCacheDir(...parts) in @hyperframes/core/cache-dir returns a folder in the cache only when HYPERFRAMES_CACHE_DIR is set, and each writer falls back to its own default otherwise. The preview's defaultStateHome() returns <cache>/state, so the record lands in <cache>/state/hyperframes/previews. The registry cache goes to <cache>/registry, the model to <cache>/models, the catalog to <cache>/catalog (HYPERFRAMES_CATALOG_ARTIFACT_DIR still wins) and the catch-up records to <cache>/catch-up. Path constants read at import became functions, so the variable is read on each call.

media-use/lib/local-media-search.mjs reads the variable itself, with the same rule. That file is copied into dist as plain .mjs and run on its own, and @hyperframes/core is only bundled into the CLI, so it cannot import the helper.

The CLI's test setup (scripts/test-home.mjs) now clears HYPERFRAMES_CACHE_DIR with the other per-user folders. With it set in the shell and not cleared, the existing "keeps its records under LOCALAPPDATA on Windows" test fails, and tests would write into that folder.

Left alone on purpose:

• The warm check's folder stays under %LOCALAPPDATA% on Windows and XDG_RUNTIME_DIR on Linux. It holds the token that authenticates the warm check server. On Windows the folder's owner is not checked, so a HYPERFRAMES_CACHE_DIR shared across accounts, as the render-slot docs suggest, would expose it. Under the sandbox its folder fails quietly and check runs cold.
• Settings under ~/.hyperframes (telemetry, update checks, project links, the running-CLI record) are configuration, not cache. They belong with HYPERFRAMES_CONFIG_DIR, in a separate change.

Test plan

• Unit tests added/updated: one test per writer sets HYPERFRAMES_CACHE_DIR and finds the path in the cache: previewLifecycle.test.ts (writes a session, state folder left empty), remote.test.ts (a fetched manifest lands in <cache>/registry), localModel.test.ts (model and tokenizer paths), localSemantic.test.ts (hasLocalVectors() reads <cache>/catalog), local-media-search.test.mjs (mediaVectorRows() reads it too) and appHistory.test.ts (the seen record is written under <cache>/catch-up). cacheDir.test.ts covers namedCacheDir. Each writer's own test fails when that file's old version is put back, and nothing else does.
  • fails without the fix: previewLifecycle.test.ts "where a preview's session is kept > is under HYPERFRAMES_CACHE_DIR when it is set, not the state folder" (expected false to be true); likewise remote.test.ts "caches manifests under HYPERFRAMES_CACHE_DIR when it is set" and appHistory.test.ts "keeps the seen record in the cache folder when it is set".
  • fails without the fix: localSemantic.test.ts "an empty HYPERFRAMES_CATALOG_ARTIFACT_DIR > counts as unset, as media search reads it". The two readers of the catalog disagreed on an empty value (?? against ||), so they could read different folders; both now treat it as unset.
  • The touched files' tests (167, plus the node test and core's 4) pass three runs in a row.
• Manual testing performed: on windows-latest, with deny ACLs on %USERPROFILE%\.cache\hyperframes and %LOCALAPPDATA%\hyperframes standing in for the sandbox and HYPERFRAMES_CACHE_DIR set to a project folder. Published 0.9.15: render with the default cache fails EPERM: operation not permitted, scandir '...\.cache\hyperframes'. With the project cache, render exits 0, but preview --background fails EPERM: operation not permitted, mkdir '...\AppData\Local\hyperframes\previews'. This branch: preview --background exits 0 in background mode with its log at <project>\.hfcache\state\hyperframes\previews\…, and --status and --stop find it. The other four writers are proven by their unit tests only.
• Documentation updated (if applicable): docs/packages/cli.mdx "Keep the environment healthy" lists what follows HYPERFRAMES_CACHE_DIR.
• Comments follow CONTRIBUTING.md "Comments": no comments added.

Size

About 50 lines of source across six call sites and the helper, about 90 of tests, one test-setup line and a docs sentence. One fix: the cache variable covers every cache writer.