hyperframes_compose reports the runtime unavailable when npm is slow, even though the cached CLI works #590

Summary

hyperframes_compose gates every operation behind a live npm view hyperframes version call with a 5-second timeout. On a slow or unreachable registry it declares the runtime unavailable and refuses to render — even when the CLI is already in the npx cache and demonstrably working.

What happened

Mid-production, two consecutive render_existing calls failed with:

HyperFrames runtime not available: npm package `hyperframes` not resolvable:
timeout (5s) — offline or slow registry. Per governance, do not swap runtimes silently.

Seconds earlier and seconds later, the same workspace passed npx hyperframes check (0 errors) and then rendered 600 frames to MP4 in ~40s through the same cached CLI. Nothing about the local install had changed; only the npm registry round-trip was slow.

Why the check does not prove what it intends

tools/video/hyperframes_compose.py:275-325. The docstring explains the probe was added because the previous PATH-only check would report runtime_available: True "even offline, even if npm was down, even if the package was unpublished."

But npx resolves from the local cache, so an offline machine with a warm cache renders fine. Registry reachability is not a precondition for rendering; it is only a precondition for first install. The probe answers "can I install this right now?" and uses it to decide "can I render right now?" — two different questions, and the second is the one the tool is being asked.

The result is also cached per-process (_npm_resolve_cache), so one slow probe poisons every subsequent call in the run.

Impact

A transient network blip fails a pipeline stage in a way the agent is explicitly forbidden to route around — the error text says "do not swap runtimes silently," and rightly so. In this run the render was completed by invoking the same HyperFrames CLI directly, which is not a runtime swap but does mean the work bypassed the tool wrapper and its checks.

Suggested fix

Try the local CLI before the registry:

1. Probe npx --offline hyperframes --version (or the resolved cache path). If it answers, the runtime is available — no network needed.
2. Fall back to npm view only when the local probe fails, since that is the case where an install is genuinely required.
3. Treat a probe timeout as unknown rather than unavailable, and let the CLI invocation itself be the source of truth.

That preserves the original intent — don't claim availability on a machine that has never installed the package — without failing renders on machines where it plainly works.

Environment

hyperframes CLI 0.8.20, Node v22.23.2, Linux x64. npx hyperframes doctor green on Node/FFmpeg/Chrome.